Save This Page
Home » xml-commons-external-1.4.01-src » javax » xml » namespace » [javadoc | source]
    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   // $Id: NamespaceContext.java 446598 2006-09-15 12:55:40Z jeremias $
   19   
   20   package javax.xml.namespace;
   21   
   22   import java.util.Iterator;
   23   
   24   /**
   25    * <p>Interface for read only XML Namespace context processing.</p>
   26    *
   27    * <p>An XML Namespace has the properties:</p>
   28    * <ul>
   29    *   <li>Namespace URI:
   30    *       Namespace name expressed as a URI to which the prefix is bound</li>
   31    *   <li>prefix: syntactically, this is the part of the attribute name
   32    *       following the <code>XMLConstants.XMLNS_ATTRIBUTE</code>
   33    *       ("xmlns") in the Namespace declaration</li>
   34    * </ul>
   35    * <p> example: <code>&lt;element xmlns:prefix="http://Namespace-name-URI"&gt;</code></p>
   36    *
   37    * <p>All <code>get*(*)</code> methods operate in the current scope
   38    * for Namespace URI and prefix resolution.</p>
   39    *
   40    * <p>Note that a Namespace URI can be bound to
   41    * <strong>multiple</strong> prefixes in the current scope.  This can
   42    * occur when multiple <code>XMLConstants.XMLNS_ATTRIBUTE</code>
   43    * ("xmlns") Namespace declarations occur in the same Start-Tag and
   44    * refer to the same Namespace URI. e.g.<br />
   45    * <pre>
   46    * &lt;element xmlns:prefix1="http://Namespace-name-URI"
   47    *          xmlns:prefix2="http://Namespace-name-URI"&gt;
   48    * </pre>
   49    * This can also occur when the same Namespace URI is used in multiple
   50    * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace
   51    * declarations in the logical parent element hierarchy.  e.g.<br />
   52    * <pre>
   53    * &lt;parent xmlns:prefix1="http://Namespace-name-URI">
   54    *   &lt;child xmlns:prefix2="http://Namespace-name-URI"&gt;
   55    *     ...
   56    *   &lt;/child&gt;
   57    * &lt;/parent&gt;
   58    * </pre></p>
   59    *
   60    * <p>A prefix can only be bound to a <strong>single</strong>
   61    * Namespace URI in the current scope.</p>
   62    *
   63    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
   64    * @version $Revision: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
   65    * @see javax.xml.XMLConstants javax.XMLConstants for declarations of common XML values
   66    * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2: Datatypes</a>
   67    * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces in XML</a>
   68    * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces in XML Errata</a>
   69    * @since 1.5
   70    */
   71   
   72   public interface NamespaceContext {
   73   
   74       /**
   75        * <p>Get Namespace URI bound to a prefix in the current scope.</p>
   76        *
   77        * <p>When requesting a Namespace URI by prefix, the following
   78        * table describes the returned Namespace URI value for all
   79        * possible prefix values:</p>
   80        *
   81        * <table border="2" rules="all" cellpadding="4"> 
   82        *   <thead>
   83        *     <tr>
   84        *       <td align="center" colspan="2">
   85        *         <code>getNamespaceURI(prefix)</code>
   86        *         return value for specified prefixes
   87        *       </td>
   88        *     </tr>
   89        *     <tr>
   90        *       <td>prefix parameter</td>
   91        *       <td>Namespace URI return value</td>
   92        *     </tr>
   93        *   </thead>
   94        *   <tbody>
   95        *     <tr>
   96        *       <td><code>DEFAULT_NS_PREFIX</code> ("")</td>
   97        *       <td>default Namespace URI in the current scope or
   98        *         <code>{@link javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}</code>   
   99        *         when there is no default Namespace URI in the current scope</td>
  100        *     </tr>
  101        *     <tr>
  102        *       <td>bound prefix</td>
  103        *       <td>Namespace URI bound to prefix in current scope</td>
  104        *     </tr>
  105        *     <tr>
  106        *       <td>unbound prefix</td>
  107        *       <td><code>{@link javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}</code> </td>
  108        *     </tr>
  109        *     <tr>
  110        *       <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
  111        *       <td><code>XMLConstants.XML_NS_URI</code>
  112        *           ("http://www.w3.org/XML/1998/namespace")</td>
  113        *     </tr>
  114        *     <tr>
  115        *       <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
  116        *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
  117        *         ("http://www.w3.org/2000/xmlns/")</td>
  118        *     </tr>
  119        *     <tr>
  120        *       <td><code>null</code></td>
  121        *       <td><code>IllegalArgumentException</code> is thrown</td>
  122        *     </tr>
  123        *    </tbody>
  124        * </table>
  125        *  
  126        * @param prefix prefix to look up
  127        * @return Namespace URI bound to prefix in the current scope
  128        */ 
  129       String getNamespaceURI(String prefix);
  130     
  131       /**
  132        * <p>Get prefix bound to Namespace URI in the current scope.</p>
  133        *
  134        * <p>To get all prefixes bound to a Namespace URI in the current
  135        * scope, use {@link #getPrefixes(String namespaceURI)}.</p>
  136        *
  137        * <p>When requesting a prefix by Namespace URI, the following
  138        * table describes the returned prefix value for all Namespace URI
  139        * values:</p>
  140        *
  141        * <table border="2" rules="all" cellpadding="4">
  142        *   <thead>
  143        *     <tr>
  144        *       <td align="center" colspan="2">
  145        *         <code>getPrefix(namespaceURI)</code> return value for
  146        *         specified Namespace URIs
  147        *       </td>
  148        *     </tr>
  149        *     <tr>
  150        *       <td>Namespace URI parameter</td>
  151        *       <td>prefix value returned</td>
  152        *     </tr>
  153        *   </thead>
  154        *   <tbody>
  155        *     <tr>
  156        *       <td>&lt;default Namespace URI&gt;</td>
  157        *       <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("")
  158        *       </td>
  159        *     </tr>
  160        *     <tr>
  161        *       <td>bound Namespace URI</td>
  162        *       <td>prefix bound to Namespace URI in the current scope,
  163        *           if multiple prefixes are bound to the Namespace URI in
  164        *           the current scope, a single arbitrary prefix, whose
  165        *           choice is implementation dependent, is returned</td>
  166        *     </tr>
  167        *     <tr>
  168        *       <td>unbound Namespace URI</td>
  169        *       <td><code>null</code></td>
  170        *     </tr>
  171        *     <tr>
  172        *       <td><code>XMLConstants.XML_NS_URI</code>
  173        *           ("http://www.w3.org/XML/1998/namespace")</td>
  174        *       <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
  175        *     </tr>
  176        *     <tr>
  177        *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
  178        *           ("http://www.w3.org/2000/xmlns/")</td>
  179        *       <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
  180        *     </tr>
  181        *     <tr>
  182        *       <td><code>null</code></td>
  183        *       <td><code>IllegalArgumentException</code> is thrown</td>
  184        *     </tr>
  185        *   </tbody>
  186        * </table>
  187        *
  188        * @param namespaceURI URI of Namespace to lookup
  189        * @return prefix bound to Namespace URI in current context
  190        */
  191       String getPrefix(String namespaceURI);
  192   
  193       /**
  194        * <p>Get all prefixes bound to a Namespace URI in the current
  195        * scope.</p>
  196        *
  197        * <p>An Iterator over String elements is returned in an arbitrary, <strong>implementation dependent</strong>, order.</p>
  198        *
  199        * <p><strong>The <code>Iterator</code> is
  200        * <em>not</em> modifiable.  e.g. the
  201        * <code>remove()</code> method will throw
  202        * <code>UnsupportedOperationException</code>.</strong></p>
  203        *
  204        * <p>When requesting prefixes by Namespace URI, the following
  205        * table describes the returned prefixes value for all Namespace
  206        * URI values:</p>
  207        *
  208        * <table border="2" rules="all" cellpadding="4">
  209        *   <thead>
  210        *     <tr>
  211        *       <td align="center" colspan="2"><code>
  212        *         getPrefixes(namespaceURI)</code> return value for
  213        *         specified Namespace URIs</td>
  214        *     </tr>
  215        *     <tr>
  216        *       <td>Namespace URI parameter</td>
  217        *       <td>prefixes value returned</td>
  218        *     </tr>
  219        *   </thead>
  220        *   <tbody>
  221        *     <tr>
  222        *       <td>bound Namespace URI,
  223        *         including the &lt;default Namespace URI&gt;</td>
  224        *       <td><code>Iterator</code> over prefixes bound to Namespace URI in
  225        *         the current scope in an arbitrary, <strong>implementation dependent</strong>,
  226        *         order</td>
  227        *     </tr>
  228        *     <tr>
  229        *       <td>unbound Namespace URI</td>
  230        *       <td>empty <code>Iterator</code></td>
  231        *     </tr>
  232        *     <tr>
  233        *       <td><code>XMLConstants.XML_NS_URI</code>
  234        *           ("http://www.w3.org/XML/1998/namespace")</td>
  235        *       <td><code>Iterator</code> with one element set to
  236        *         <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
  237        *     </tr>
  238        *     <tr>
  239        *       <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
  240        *           ("http://www.w3.org/2000/xmlns/")</td>
  241        *       <td><code>Iterator</code> with one element set to
  242        *         <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
  243        *     </tr>
  244        *     <tr>
  245        *       <td><code>null</code></td>
  246        *       <td><code>IllegalArgumentException</code> is thrown</td>
  247        *     </tr>
  248        *   </tbody>
  249        * </table>
  250        *
  251        * @param namespaceURI URI of Namespace to lookup
  252        * @return <code>Iterator</code> for all prefixes bound to the
  253        * Namespace URI in the current scope
  254        */
  255       Iterator getPrefixes(String namespaceURI);
  256   }

Save This Page
Home » xml-commons-external-1.4.01-src » javax » xml » namespace » [javadoc | source]