1 /*
   2  * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.namespace;
  27 
  28 import java.util.Iterator;
  29 
  30 /**
  31  * Interface for read only XML Namespace context processing.
  32  *
  33  * <p>An XML Namespace has the properties:
  34  * <ul>
  35  *   <li>Namespace URI:
  36  *       Namespace name expressed as a URI to which the prefix is bound</li>
  37  *   <li>prefix: syntactically, this is the part of the attribute name
  38  *       following the {@code XMLConstants.XMLNS_ATTRIBUTE}
  39  *       ("xmlns") in the Namespace declaration</li>
  40  * </ul>
  41  * <p>example:
  42  * {@code <element xmlns:prefix="http://Namespace-name-URI">}
  43  *
  44  * <p>All {@code get*(*)} methods operate in the current scope
  45  * for Namespace URI and prefix resolution.
  46  *
  47  * <p>Note that a Namespace URI can be bound to
  48  * <strong>multiple</strong> prefixes in the current scope.  This can
  49  * occur when multiple {@code XMLConstants.XMLNS_ATTRIBUTE}
  50  * ("xmlns") Namespace declarations occur in the same Start-Tag and
  51  * refer to the same Namespace URI. e.g.<br>
  52  * <pre> {@code
  53  * <element xmlns:prefix1="http://Namespace-name-URI"
  54  *          xmlns:prefix2="http://Namespace-name-URI"> }
  55  * </pre>
  56  * This can also occur when the same Namespace URI is used in multiple
  57  * {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns") Namespace
  58  * declarations in the logical parent element hierarchy.  e.g.<br>
  59  * <pre> {@code
  60  * <parent xmlns:prefix1="http://Namespace-name-URI">
  61  *   <child xmlns:prefix2="http://Namespace-name-URI">
  62  *     ...
  63  *   </child>
  64  * </parent> }
  65  * </pre>
  66  *
  67  * <p>A prefix can only be bound to a <strong>single</strong>
  68  * Namespace URI in the current scope.
  69  *
  70  * @author Jeff Suttor
  71  * @see javax.xml.XMLConstants
  72  *   javax.xml.XMLConstants for declarations of common XML values
  73  * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
  74  *   XML Schema Part2: Datatypes</a>
  75  * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
  76  *   Namespaces in XML</a>
  77  * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">
  78  *   Namespaces in XML Errata</a>
  79  * @since 1.5
  80  */
  81 
  82 public interface NamespaceContext {
  83 
  84     /**
  85      * Get Namespace URI bound to a prefix in the current scope.
  86      *
  87      * <p>When requesting a Namespace URI by prefix, the following
  88      * table describes the returned Namespace URI value for all
  89      * possible prefix values:
  90      *
  91      * <table class="striped">
  92      *   <caption>Return value for specified prefixes</caption>
  93      *   <thead>
  94      *     <tr>
  95      *       <th scope="col">prefix parameter</th>
  96      *       <th scope="col">Namespace URI return value</th>
  97      *     </tr>
  98      *   </thead>
  99      *   <tbody>
 100      *     <tr>
 101      *       <th scope="row">{@code DEFAULT_NS_PREFIX} ("")</th>
 102      *       <td>default Namespace URI in the current scope or
 103      *         <code> {@link
 104      *         javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
 105      *         </code>
 106      *         when there is no default Namespace URI in the current scope</td>
 107      *     </tr>
 108      *     <tr>
 109      *       <th scope="row">bound prefix</th>
 110      *       <td>Namespace URI bound to prefix in current scope</td>
 111      *     </tr>
 112      *     <tr>
 113      *       <th scope="row">unbound prefix</th>
 114      *       <td>
 115      *         <code> {@link
 116      *         javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
 117      *         </code>
 118      *       </td>
 119      *     </tr>
 120      *     <tr>
 121      *       <th scope="row">{@code XMLConstants.XML_NS_PREFIX} ("xml")</th>
 122      *       <td>{@code XMLConstants.XML_NS_URI}
 123      *           ("http://www.w3.org/XML/1998/namespace")</td>
 124      *     </tr>
 125      *     <tr>
 126      *       <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</th>
 127      *       <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
 128      *         ("http://www.w3.org/2000/xmlns/")</td>
 129      *     </tr>
 130      *     <tr>
 131      *       <th scope="row">{@code null}</th>
 132      *       <td>{@code IllegalArgumentException} is thrown</td>
 133      *     </tr>
 134      *    </tbody>
 135      * </table>
 136      *
 137      * @param prefix prefix to look up
 138      *
 139      * @return Namespace URI bound to prefix in the current scope
 140      *
 141      * @throws IllegalArgumentException When {@code prefix} is
 142      *   {@code null}
 143      */
 144     String getNamespaceURI(String prefix);
 145 
 146     /**
 147      * Get prefix bound to Namespace URI in the current scope.
 148      *
 149      * <p>To get all prefixes bound to a Namespace URI in the current
 150      * scope, use {@link #getPrefixes(String namespaceURI)}.
 151      *
 152      * <p>When requesting a prefix by Namespace URI, the following
 153      * table describes the returned prefix value for all Namespace URI
 154      * values:
 155      *
 156      * <table class="striped">
 157      * <caption>Return value for specified Namespace URIs</caption>
 158      *   <thead>
 159      *     <tr>
 160      *       <th scope="col">Namespace URI parameter</th>
 161      *       <th scope="col">prefix value returned</th>
 162      *     </tr>
 163      *   </thead>
 164      *   <tbody>
 165      *     <tr>
 166      *       <th scope="row">{@code <default Namespace URI>}</th>
 167      *       <td>{@code XMLConstants.DEFAULT_NS_PREFIX} ("")
 168      *       </td>
 169      *     </tr>
 170      *     <tr>
 171      *       <th scope="row">bound Namespace URI</th>
 172      *       <td>prefix bound to Namespace URI in the current scope,
 173      *           if multiple prefixes are bound to the Namespace URI in
 174      *           the current scope, a single arbitrary prefix, whose
 175      *           choice is implementation dependent, is returned</td>
 176      *     </tr>
 177      *     <tr>
 178      *       <th scope="row">unbound Namespace URI</th>
 179      *       <td>{@code null}</td>
 180      *     </tr>
 181      *     <tr>
 182      *       <th scope="row">{@code XMLConstants.XML_NS_URI}
 183      *           ("http://www.w3.org/XML/1998/namespace")</th>
 184      *       <td>{@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
 185      *     </tr>
 186      *     <tr>
 187      *       <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
 188      *           ("http://www.w3.org/2000/xmlns/")</th>
 189      *       <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
 190      *     </tr>
 191      *     <tr>
 192      *       <th scope="row">{@code null}</th>
 193      *       <td>{@code IllegalArgumentException} is thrown</td>
 194      *     </tr>
 195      *   </tbody>
 196      * </table>
 197      *
 198      * @param namespaceURI URI of Namespace to lookup
 199      *
 200      * @return prefix bound to Namespace URI in current context
 201      *
 202      * @throws IllegalArgumentException When {@code namespaceURI} is
 203      *   {@code null}
 204      */
 205     String getPrefix(String namespaceURI);
 206 
 207     /**
 208      * Get all prefixes bound to a Namespace URI in the current
 209      * scope.
 210      *
 211      * <p>An Iterator over String elements is returned in an arbitrary,
 212      * <strong>implementation dependent</strong>, order.
 213      *
 214      * <p><strong>The {@code Iterator} is
 215      * <em>not</em> modifiable.  e.g. the
 216      * {@code remove()} method will throw
 217      * {@code UnsupportedOperationException}.</strong>
 218      *
 219      * <p>When requesting prefixes by Namespace URI, the following
 220      * table describes the returned prefixes value for all Namespace
 221      * URI values:
 222      *
 223      * <table class="striped">
 224      *   <caption>Return value for specified Namespace URIs</caption>
 225      *   <thead>
 226      *     <tr>
 227      *       <th scope="col">Namespace URI parameter</th>
 228      *       <th scope="col">prefixes value returned</th>
 229      *     </tr>
 230      *   </thead>
 231      *   <tbody>
 232      *     <tr>
 233      *       <th scope="row">bound Namespace URI,
 234      *         including the {@code <default Namespace URI>}</th>
 235      *       <td>
 236      *         {@code Iterator} over prefixes bound to Namespace URI in
 237      *         the current scope in an arbitrary,
 238      *         <strong>implementation dependent</strong>,
 239      *         order
 240      *       </td>
 241      *     </tr>
 242      *     <tr>
 243      *       <th scope="row">unbound Namespace URI</th>
 244      *       <td>empty {@code Iterator}</td>
 245      *     </tr>
 246      *     <tr>
 247      *       <th scope="row">{@code XMLConstants.XML_NS_URI}
 248      *           ("http://www.w3.org/XML/1998/namespace")</th>
 249      *       <td>{@code Iterator} with one element set to
 250      *         {@code XMLConstants.XML_NS_PREFIX} ("xml")</td>
 251      *     </tr>
 252      *     <tr>
 253      *       <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI}
 254      *           ("http://www.w3.org/2000/xmlns/")</th>
 255      *       <td>{@code Iterator} with one element set to
 256      *         {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td>
 257      *     </tr>
 258      *     <tr>
 259      *       <th scope="row">{@code null}</th>
 260      *       <td>{@code IllegalArgumentException} is thrown</td>
 261      *     </tr>
 262      *   </tbody>
 263      * </table>
 264      *
 265      * @param namespaceURI URI of Namespace to lookup
 266      *
 267      * @return {@code Iterator} for all prefixes bound to the
 268      *   Namespace URI in the current scope
 269      *
 270      * @throws IllegalArgumentException When {@code namespaceURI} is
 271      *   {@code null}
 272      */
 273     Iterator<String> getPrefixes(String namespaceURI);
 274 }