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 } 245