/* * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.xml.namespace; import java.util.Iterator; /** * Interface for read only XML Namespace context processing. * *
An XML Namespace has the properties: *
example:
* {@code All {@code 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 {@code XMLConstants.XMLNS_ATTRIBUTE}
* ("xmlns") Namespace declarations occur in the same Start-Tag and
* refer to the same Namespace URI. e.g. A prefix can only be bound to a single
* Namespace URI in the current scope.
*
* @author Jeff Suttor
* @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:
*
* 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:
*
* An Iterator over String elements is returned in an arbitrary,
* implementation dependent, order.
*
* The {@code Iterator} is
* not modifiable. e.g. the
* {@code remove()} method will throw
* {@code UnsupportedOperationException}.
*
* When requesting prefixes by Namespace URI, the following
* table describes the returned prefixes value for all Namespace
* URI values:
*
*
* {@code
*
* This can also occur when the same Namespace URI is used in multiple
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns") Namespace
* declarations in the logical parent element hierarchy. e.g.
* {@code
*
*
*
*
*
* @param prefix prefix to look up
*
* @return Namespace URI bound to prefix in the current scope
*
* @throws IllegalArgumentException When {@code prefix} is
* {@code null}
*/
String getNamespaceURI(String prefix);
/**
* Get prefix bound to Namespace URI in the current scope.
*
*
*
*
*
* prefix parameter
* Namespace URI return value
*
*
* {@code 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("")}
*
*
*
* {@code XMLConstants.XML_NS_PREFIX} ("xml")
* {@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")
*
*
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")
* {@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")
*
*
*
* {@code null}
* {@code IllegalArgumentException} is thrown
*
*
*
* @param namespaceURI URI of Namespace to lookup
*
* @return prefix bound to Namespace URI in current context
*
* @throws IllegalArgumentException When {@code namespaceURI} is
* {@code null}
*/
String getPrefix(String namespaceURI);
/**
* Get all prefixes bound to a Namespace URI in the current
* scope.
*
*
*
*
*
* Namespace URI parameter
* prefix value returned
*
*
* {@code
* {@code 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
* {@code null}
*
*
* {@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")
* {@code XMLConstants.XML_NS_PREFIX} ("xml")
*
*
* {@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")
*
*
*
* {@code null}
* {@code IllegalArgumentException} is thrown
*
*
*
* @param namespaceURI URI of Namespace to lookup
*
* @return {@code Iterator} for all prefixes bound to the
* Namespace URI in the current scope
*
* @throws IllegalArgumentException When {@code namespaceURI} is
* {@code null}
*/
Iterator
*
*
*
* Namespace URI parameter
* prefixes value returned
*
*
* bound Namespace URI,
* including the {@code
*
* {@code Iterator} over prefixes bound to Namespace URI in
* the current scope in an arbitrary,
* implementation dependent,
* order
*
*
*
* unbound Namespace URI
* empty {@code Iterator}
*
*
* {@code XMLConstants.XML_NS_URI}
* ("http://www.w3.org/XML/1998/namespace")
* {@code Iterator} with one element set to
* {@code XMLConstants.XML_NS_PREFIX} ("xml")
*
*
* {@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
* ("http://www.w3.org/2000/xmlns/")
* {@code Iterator} with one element set to
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")
*
*
*
* {@code null}
* {@code IllegalArgumentException} is thrown
*