/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ // $Id: NamespaceContext.java 446598 2006-09-15 12:55:40Z jeremias $ 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: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $ * @see javax.xml.XMLConstants javax.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/")
`null`	`IllegalArgumentException` is thrown

* * @param prefix prefix to look up * @return Namespace URI bound to prefix in the current scope */ 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")
`null`	`IllegalArgumentException` is thrown

* * @param namespaceURI URI of Namespace to lookup * @return prefix bound to Namespace URI in current context */ 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")
`null`	`IllegalArgumentException` is thrown

* * @param namespaceURI URI of Namespace to lookup * @return Iterator for all prefixes bound to the * Namespace URI in the current scope */ Iterator getPrefixes(String namespaceURI); }