javax.xml.namespace.NamespaceContext Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* https://jaxp.dev.java.net/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* HEADER in each file and include the License file at
* https://jaxp.dev.java.net/CDDLv1.0.html
* If applicable add the following below this CDDL HEADER
* with the fields enclosed by brackets "[]" replaced with
* your own identifying information: Portions Copyright
* [year] [name of copyright owner]
*/
/*
* $Id: NamespaceContext.java,v 1.3 2005/11/03 19:34:20 jeffsuttor Exp $
* %W% %E%
*
* Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
*/
package javax.xml.namespace;
import java.util.Iterator;
/**
* Interface for read only XML Namespace context processing.
*
* An XML Namespace has the properties:
*
* - Namespace URI:
* Namespace name expressed as a URI to which the prefix is bound
* - prefix: syntactically, this is the part of the attribute name
* following the
XMLConstants.XMLNS_ATTRIBUTE
* ("xmlns") in the Namespace declaration
*
* example:
* <element xmlns:prefix="http://Namespace-name-URI">
*
* All get*(*) methods operate in the current scope
* for Namespace URI and prefix resolution.
*
* Note that a Namespace URI can be bound to
* multiple prefixes in the current scope. This can
* occur when multiple XMLConstants.XMLNS_ATTRIBUTE
* ("xmlns") Namespace declarations occur in the same Start-Tag and
* refer to the same Namespace URI. e.g.
*
* <element xmlns:prefix1="http://Namespace-name-URI"
* xmlns:prefix2="http://Namespace-name-URI">
*
* This can also occur when the same Namespace URI is used in multiple
* XMLConstants.XMLNS_ATTRIBUTE ("xmlns") Namespace
* declarations in the logical parent element hierarchy. e.g.
*
* <parent xmlns:prefix1="http://Namespace-name-URI">
* <child xmlns:prefix2="http://Namespace-name-URI">
* ...
* </child>
* </parent>
*
*
* A prefix can only be bound to a single
* Namespace URI in the current scope.
*
* @author Jeff Suttor
* @version $Revision: 1.3 $, $Date: 2005/11/03 19:34:20 $
* @see javax.xml.XMLConstants
* javax.xml.XMLConstants for declarations of common XML values
* @see
* XML Schema Part2: Datatypes
* @see
* Namespaces in XML
* @see
* Namespaces in XML Errata
* @since 1.5
*/
public interface NamespaceContext {
/**
* Get Namespace URI bound to a prefix in the current scope.
*
* When requesting a Namespace URI by prefix, the following
* table describes the returned Namespace URI value for all
* possible prefix values:
*
*
*
*
*
* getNamespaceURI(prefix)
* return value for specified prefixes
*
*
*
* prefix parameter
* Namespace URI return value
*
*
*
*
* DEFAULT_NS_PREFIX ("")default Namespace URI in the current scope or
* {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
*
* when there is no default Namespace URI in the current scope
*
*
* bound prefix
* Namespace URI bound to prefix in current scope
*
*
* unbound prefix
*
* {@link
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
*
*
*
*
* XMLConstants.XML_NS_PREFIX ("xml")XMLConstants.XML_NS_URI
* ("http://www.w3.org/XML/1998/namespace")
*
* XMLConstants.XMLNS_ATTRIBUTE ("xmlns")XMLConstants.XMLNS_ATTRIBUTE_NS_URI
* ("http://www.w3.org/2000/xmlns/")
*
* nullIllegalArgumentException is thrown
*
*
*
* @param prefix prefix to look up
*
* @return Namespace URI bound to prefix in the current scope
*
* @throws IllegalArgumentException When prefix is
* null
*/
String getNamespaceURI(String prefix);
/**
* Get prefix bound to Namespace URI in the current scope.
*
* To get all prefixes bound to a Namespace URI in the current
* scope, use {@link #getPrefixes(String namespaceURI)}.
*
* When requesting a prefix by Namespace URI, the following
* table describes the returned prefix value for all Namespace URI
* values:
*
*
*
*
*
* getPrefix(namespaceURI) return value for
* specified Namespace URIs
*
*
*
* Namespace URI parameter
* prefix value returned
*
*
*
*
* <default Namespace URI>
* XMLConstants.DEFAULT_NS_PREFIX ("")
*
*
* bound Namespace URI
* prefix bound to Namespace URI in the current scope,
* if multiple prefixes are bound to the Namespace URI in
* the current scope, a single arbitrary prefix, whose
* choice is implementation dependent, is returned
*
*
* unbound Namespace URI
* null
*
* XMLConstants.XML_NS_URI
* ("http://www.w3.org/XML/1998/namespace")XMLConstants.XML_NS_PREFIX ("xml")
*
* XMLConstants.XMLNS_ATTRIBUTE_NS_URI
* ("http://www.w3.org/2000/xmlns/")XMLConstants.XMLNS_ATTRIBUTE ("xmlns")
*
* nullIllegalArgumentException is thrown
*
*
*
* @param namespaceURI URI of Namespace to lookup
*
* @return prefix bound to Namespace URI in current context
*
* @throws IllegalArgumentException When namespaceURI is
* null
*/
String getPrefix(String namespaceURI);
/**
* Get all prefixes bound to a Namespace URI in the current
* scope.
*
* An Iterator over String elements is returned in an arbitrary,
* implementation dependent, order.
*
* The Iterator is
* not modifiable. e.g. the
* remove() method will throw
* UnsupportedOperationException.
*
* When requesting prefixes by Namespace URI, the following
* table describes the returned prefixes value for all Namespace
* URI values:
*
*
*
*
*
* getPrefixes(namespaceURI) return value for
* specified Namespace URIs
*
* Namespace URI parameter
* prefixes value returned
*
*
*
*
* bound Namespace URI,
* including the <default Namespace URI>
*
* Iterator over prefixes bound to Namespace URI in
* the current scope in an arbitrary,
* implementation dependent,
* order
*
*
*
* unbound Namespace URI
* empty Iterator
*
*
* XMLConstants.XML_NS_URI
* ("http://www.w3.org/XML/1998/namespace")Iterator with one element set to
* XMLConstants.XML_NS_PREFIX ("xml")
*
* XMLConstants.XMLNS_ATTRIBUTE_NS_URI
* ("http://www.w3.org/2000/xmlns/")Iterator with one element set to
* XMLConstants.XMLNS_ATTRIBUTE ("xmlns")
*
* nullIllegalArgumentException is thrown
*
*
*
* @param namespaceURI URI of Namespace to lookup
*
* @return Iterator for all prefixes bound to the
* Namespace URI in the current scope
*
* @throws IllegalArgumentException When namespaceURI is
* null
*/
Iterator getPrefixes(String namespaceURI);
}