1. // $Id: NamespaceContext.java,v 1.4.16.1 2004/06/28 18:20:38 ndw Exp $

  2. 

  3. /*

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.xml.namespace;

  9. 

  10. import java.util.Iterator;

  11. 

  12. /**

  13.  * <p>Interface for read only XML Namespace context processing.</p>

  14.  *

  15.  * <p>An XML Namespace has the properties:</p>

  16.  * <ul>

  17.  *   <li>Namespace URI:

  18.  *       Namespace name expressed as a URI to which the prefix is bound</li>

  19.  *   <li>prefix: syntactically, this is the part of the attribute name

  20.  *       following the <code>XMLConstants.XMLNS_ATTRIBUTE</code>

  21.  *       ("xmlns") in the Namespace declaration</li>

  22.  * </ul>

  23.  * <p> example: <code><element xmlns:prefix="http://Namespace-name-URI"></code></p>

  24.  *

  25.  * <p>All <code>get*(*)</code> methods operate in the current scope

  26.  * for Namespace URI and prefix resolution.</p>

  27.  *

  28.  * <p>Note that a Namespace URI can be bound to

  29.  * <strong>multiple</strong> prefixes in the current scope.  This can

  30.  * occur when multiple <code>XMLConstants.XMLNS_ATTRIBUTE</code>

  31.  * ("xmlns") Namespace declarations occur in the same Start-Tag and

  32.  * refer to the same Namespace URI. e.g.<br />

  33.  * <pre>

  34.  * <element xmlns:prefix1="http://Namespace-name-URI"

  35.  *          xmlns:prefix2="http://Namespace-name-URI">

  36.  * </pre>

  37.  * This can also occur when the same Namespace URI is used in multiple

  38.  * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace

  39.  * declarations in the logical parent element hierarchy.  e.g.<br />

  40.  * <pre>

  41.  * <parent xmlns:prefix1="http://Namespace-name-URI">

  42.  *   <child xmlns:prefix2="http://Namespace-name-URI">

  43.  *     ...

  44.  *   </child>

  45.  * </parent>

  46.  * </pre></p>

  47.  *

  48.  * <p>A prefix can only be bound to a <strong>single</strong>

  49.  * Namespace URI in the current scope.</p>

  50.  *

  51.  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>

  52.  * @version $Revision: 1.4.16.1 $, $Date: 2004/06/28 18:20:38 $

  53.  * @see javax.xml.XMLConstants javax.XMLConstants for declarations of common XML values

  54.  * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2: Datatypes</a>

  55.  * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces in XML</a>

  56.  * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces in XML Errata</a>

  57.  * @since 1.5

  58.  */

  59. 

  60. public interface NamespaceContext {

  61. 

  62.     /**

  63.      * <p>Get Namespace URI bound to a prefix in the current scope.</p>

  64.      *

  65.      * <p>When requesting a Namespace URI by prefix, the following

  66.      * table describes the returned Namespace URI value for all

  67.      * possible prefix values:</p>

  68.      *

  69.      * <table border="2" rules="all" cellpadding="4"> 

  70.      *   <thead>

  71.      *     <tr>

  72.      *       <td align="center" colspan="2">

  73.      *         <code>getNamespaceURI(prefix)</code>

  74.      *         return value for specified prefixes

  75.      *       </td>

  76.      *     </tr>

  77.      *     <tr>

  78.      *       <td>prefix parameter</td>

  79.      *       <td>Namespace URI return value</td>

  80.      *     </tr>

  81.      *   </thead>

  82.      *   <tbody>

  83.      *     <tr>

  84.      *       <td><code>DEFAULT_NS_PREFIX</code> ("")</td>

  85.      *       <td>default Namespace URI in the current scope or

  86.      *         <code>{@link javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}</code>   

  87.      *         when there is no default Namespace URI in the current scope</td>

  88.      *     </tr>

  89.      *     <tr>

  90.      *       <td>bound prefix</td>

  91.      *       <td>Namespace URI bound to prefix in current scope</td>

  92.      *     </tr>

  93.      *     <tr>

  94.      *       <td>unbound prefix</td>

  95.      *       <td><code>{@link javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}</code> </td>

  96.      *     </tr>

  97.      *     <tr>

  98.      *       <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>

  99.      *       <td><code>XMLConstants.XML_NS_URI</code>

  100.      *           ("http://www.w3.org/XML/1998/namespace")</td>

  101.      *     </tr>

  102.      *     <tr>

  103.      *       <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>

  104.      *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>

  105.      *         ("http://www.w3.org/2000/xmlns/")</td>

  106.      *     </tr>

  107.      *     <tr>

  108.      *       <td><code>null</code></td>

  109.      *       <td><code>IllegalArgumentException</code> is thrown</td>

  110.      *     </tr>

  111.      *    </tbody>

  112.      * </table>

  113.      *  

  114.      * @param prefix prefix to look up

  115.      * @return Namespace URI bound to prefix in the current scope

  116.      */ 

  117.     String getNamespaceURI(String prefix);

  118.   

  119.     /**

  120.      * <p>Get prefix bound to Namespace URI in the current scope.</p>

  121.      *

  122.      * <p>To get all prefixes bound to a Namespace URI in the current

  123.      * scope, use {@link #getPrefixes(String namespaceURI)}.</p>

  124.      *

  125.      * <p>When requesting a prefix by Namespace URI, the following

  126.      * table describes the returned prefix value for all Namespace URI

  127.      * values:</p>

  128.      *

  129.      * <table border="2" rules="all" cellpadding="4">

  130.      *   <thead>

  131.      *     <tr>

  132.      *       <td align="center" colspan="2">

  133.      *         <code>getPrefix(namespaceURI)</code> return value for

  134.      *         specified Namespace URIs

  135.      *       </td>

  136.      *     </tr>

  137.      *     <tr>

  138.      *       <td>Namespace URI parameter</td>

  139.      *       <td>prefix value returned</td>

  140.      *     </tr>

  141.      *   </thead>

  142.      *   <tbody>

  143.      *     <tr>

  144.      *       <td><default Namespace URI></td>

  145.      *       <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("")

  146.      *       </td>

  147.      *     </tr>

  148.      *     <tr>

  149.      *       <td>bound Namespace URI</td>

  150.      *       <td>prefix bound to Namespace URI in the current scope,

  151.      *           if multiple prefixes are bound to the Namespace URI in

  152.      *           the current scope, a single arbitrary prefix, whose

  153.      *           choice is implementation dependent, is returned</td>

  154.      *     </tr>

  155.      *     <tr>

  156.      *       <td>unbound Namespace URI</td>

  157.      *       <td><code>null</code></td>

  158.      *     </tr>

  159.      *     <tr>

  160.      *       <td><code>XMLConstants.XML_NS_URI</code>

  161.      *           ("http://www.w3.org/XML/1998/namespace")</td>

  162.      *       <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>

  163.      *     </tr>

  164.      *     <tr>

  165.      *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>

  166.      *           ("http://www.w3.org/2000/xmlns/")</td>

  167.      *       <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>

  168.      *     </tr>

  169.      *     <tr>

  170.      *       <td><code>null</code></td>

  171.      *       <td><code>IllegalArgumentException</code> is thrown</td>

  172.      *     </tr>

  173.      *   </tbody>

  174.      * </table>

  175.      *

  176.      * @param namespaceURI URI of Namespace to lookup

  177.      * @return prefix bound to Namespace URI in current context

  178.      */

  179.     String getPrefix(String namespaceURI);

  180. 

  181.     /**

  182.      * <p>Get all prefixes bound to a Namespace URI in the current

  183.      * scope.</p>

  184.      *

  185.      * <p>An Iterator over String elements is returned in an arbitrary, <strong>implementation dependent</strong>, order.</p>

  186.      *

  187.      * <p><strong>The <code>Iterator</code> is

  188.      * <em>not</em> modifiable.  e.g. the

  189.      * <code>remove()</code> method will throw

  190.      * <code>UnsupportedOperationException</code>.</strong></p>

  191.      *

  192.      * <p>When requesting prefixes by Namespace URI, the following

  193.      * table describes the returned prefixes value for all Namespace

  194.      * URI values:</p>

  195.      *

  196.      * <table border="2" rules="all" cellpadding="4">

  197.      *   <thead>

  198.      *     <tr>

  199.      *       <td align="center" colspan="2"><code>

  200.      *         getPrefixes(namespaceURI)</code> return value for

  201.      *         specified Namespace URIs</td>

  202.      *     </tr>

  203.      *     <tr>

  204.      *       <td>Namespace URI parameter</td>

  205.      *       <td>prefixes value returned</td>

  206.      *     </tr>

  207.      *   </thead>

  208.      *   <tbody>

  209.      *     <tr>

  210.      *       <td>bound Namespace URI,

  211.      *         including the <default Namespace URI></td>

  212.      *       <td><code>Iterator</code> over prefixes bound to Namespace URI in

  213.      *         the current scope in an arbitrary, <strong>implementation dependent</strong>,

  214.      *         order</td>

  215.      *     </tr>

  216.      *     <tr>

  217.      *       <td>unbound Namespace URI</td>

  218.      *       <td>empty <code>Iterator</code></td>

  219.      *     </tr>

  220.      *     <tr>

  221.      *       <td><code>XMLConstants.XML_NS_URI</code>

  222.      *           ("http://www.w3.org/XML/1998/namespace")</td>

  223.      *       <td><code>Iterator</code> with one element set to

  224.      *         <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>

  225.      *     </tr>

  226.      *     <tr>

  227.      *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>

  228.      *           ("http://www.w3.org/2000/xmlns/")</td>

  229.      *       <td><code>Iterator</code> with one element set to

  230.      *         <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>

  231.      *     </tr>

  232.      *     <tr>

  233.      *       <td><code>null</code></td>

  234.      *       <td><code>IllegalArgumentException</code> is thrown</td>

  235.      *     </tr>

  236.      *   </tbody>

  237.      * </table>

  238.      *

  239.      * @param namespaceURI URI of Namespace to lookup

  240.      * @return <code>Iterator</code> for all prefixes bound to the

  241.      * Namespace URI in the current scope

  242.      */

  243.     Iterator getPrefixes(String namespaceURI);

  244. }