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 20package javax.xml.namespace; 21 22import 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><element xmlns:prefix="http://Namespace-name-URI"></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 * <element xmlns:prefix1="http://Namespace-name-URI" 47 * xmlns:prefix2="http://Namespace-name-URI"> 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 * <parent xmlns:prefix1="http://Namespace-name-URI"> 54 * <child xmlns:prefix2="http://Namespace-name-URI"> 55 * ... 56 * </child> 57 * </parent> 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 05:55:40 -0700 (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 72public 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><default Namespace URI></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 <default Namespace URI></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} 257