001 // $Id: NamespaceContext.java,v 1.6 2003/01/13 21:15:52 ryans Exp $ 002 003 004 005 package javax.xml.namespace; 006 007 008 009 import java.util.Iterator; 010 011 012 013 /** 014 015 * Interface for read only XML Namespace context processing. 016 017 * 018 019 * <p>An XML Namespace has the properties:</p> 020 021 * <ul> 022 023 * <li>Namespace URI: 024 025 * Namespace name expressed as a URI to which the prefix is bound</li> 026 027 * <li>prefix: syntactically, this is the part of the attribute name 028 029 * following the <code>XMLConstants.XMLNS_ATTRIBUTE</code> 030 031 * ("xmlns") in the Namespace declaration</li> 032 033 * <li>example: 034 035 * <code><element xmlns:prefix="http://Namespace-name-URI"></code> 036 037 * </li> 038 039 * </ul> 040 041 * 042 043 * <p>All <code>get*(*)</code> methods operate in the current scope 044 045 * for Namespace URI and prefix resolution.</p> 046 047 * 048 049 * <p>Note that a Namespace URI can be bound to 050 051 * <strong>multiple</strong> prefixes in the current scope. This can 052 053 * occur when multiple <code>XMLConstants.XMLNS_ATTRIBUTE</code> 054 055 * ("xmlns") Namespace declarations occur in the same Start-Tag and 056 057 * refer to the same Namespace URI. e.g.<br /> 058 059 * <code><pre> 060 061 * <element xmlns:prefix1="http://Namespace-name-URI" 062 063 * xmlns:prefix2="http://Namespace-name-URI"> 064 065 * </pre></code><br /> 066 067 * This can also occur when the same Namespace URI is used in multiple 068 069 * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace 070 071 * declarations in the logical parent element hierarchy. e.g.<br /> 072 073 * <code><pre> 074 075 * <parent xmlns:prefix1="http://Namespace-name-URI"> 076 077 * <child xmlns:prefix2="http://Namespace-name-URI"> 078 079 * ... 080 081 * </child> 082 083 * </parent> 084 085 * </pre></code></p> 086 087 * 088 089 * <p>A prefix can only be bound to a <strong>single</strong> 090 091 * Namespace URI in the current scope.</p> 092 093 * 094 095 * @author <a href="http://jcp.org/">JAXP Java Community Process</a> 096 097 * @author <a href="http://java.sun.com/">JAXP Reference Implementation</a> 098 099 * @version 1.0.proposed 100 101 * @see javax.xml.XMLConstants declarations of common XML values 102 103 * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames"> 104 105 * Namespaces in XML</a> 106 107 * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata"> 108 109 * Namespaces in XML Errata</a> 110 111 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName"> 112 113 * XML Schema Part2: Datatypes</a> 114 115 */ 116 117 118 119 public interface NamespaceContext { 120 121 122 123 /** 124 125 * Get Namespace URI bound to a prefix in the current scope. 126 127 * 128 129 * <p>When requesting a Namespace URI by prefix, the following 130 131 * table describes the returned Namespace URI value for all 132 133 * possible prefix values:</p> 134 135 * 136 137 * <table border="2" rules="all" cellpadding="4"> 138 139 * <thead> 140 141 * <tr> 142 143 * <th align="center" colspan="2"> 144 145 * <code>getNamespaceURI(prefix)</code> 146 147 * return value for specified prefixes 148 149 * </th> 150 151 * </tr> 152 153 * </thead> 154 155 * <tbody> 156 157 * <tr> 158 159 * <th>prefix parameter</th> 160 161 * <th>Namespace URI return value</th> 162 163 * </tr> 164 165 * <tr> 166 167 * <td><code>DEFAULT_NS_PREFIX</code> ("")</td> 168 169 * <td>default Namespace URI in the current scope or <code>null</code> 170 171 * when there is no default Namespace URI in the current scope</td> 172 173 * </tr> 174 175 * <tr> 176 177 * <td>bound prefix</td> 178 179 * <td>Namespace URI bound to prefix in current scope</td> 180 181 * </tr> 182 183 * <tr> 184 185 * <td>unbound prefix</td> 186 187 * <td><code>null</code></td> 188 189 * </tr> 190 191 * <tr> 192 193 * <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> 194 195 * <td><code>XMLConstants.XML_NS_URI</code> 196 197 * ("http://www.w3.org/XML/1998/namespace")</td> 198 199 * </tr> 200 201 * <tr> 202 203 * <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> 204 205 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> 206 207 * ("http://www.w3.org/2000/xmlns/")</td> 208 209 * </tr> 210 211 * <tr> 212 213 * <td><code>null</code></td> 214 215 * <td><code>IllegalArgumentException</code> is thrown</td> 216 217 * </tr> 218 219 * </tbody> 220 221 * </table> 222 223 * 224 225 * @param prefix prefix to look up 226 227 * @return Namespace URI bound to prefix in the current scope 228 229 */ 230 231 String getNamespaceURI(String prefix); 232 233 234 235 /** 236 237 * Get prefix bound to Namespace URI in the current scope. 238 239 * 240 241 * <p>To get all prefixes bound to a Namespace URI in the current 242 243 * scope, use {@link #getPrefixes(String namespaceURI)}.</p> 244 245 * 246 247 * <p>When requesting a prefix by Namespace URI, the following 248 249 * table describes the returned prefix value for all Namespace URI 250 251 * values:</p> 252 253 * 254 255 * <table border="2" rules="all" cellpadding="4"> 256 257 * <thead> 258 259 * <tr> 260 261 * <th align="center" colspan="2"> 262 263 * <code>getPrefix(namespaceURI)</code> return value for 264 265 * specified Namespace URIs 266 267 * </th> 268 269 * </tr> 270 271 * </thead> 272 273 * <tbody> 274 275 * <tr> 276 277 * <th>Namespace URI parameter</th> 278 279 * <th>prefix value returned</th> 280 281 * </tr> 282 283 * <tr> 284 285 * <td><default Namespace URI></td> 286 287 * <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("") 288 289 * </td> 290 291 * </tr> 292 293 * <tr> 294 295 * <td>bound Namespace URI</td> 296 297 * <td>prefix bound to Namespace URI in the current scope, 298 299 * if multiple prefixes are bound to the Namespace URI in 300 301 * the current scope, a single arbitrary prefix, whose 302 303 * choice is implementation dependent, is returned</td> 304 305 * </tr> 306 307 * <tr> 308 309 * <td>unbound Namespace URI</td> 310 311 * <td><code>null</code></td> 312 313 * </tr> 314 315 * <tr> 316 317 * <td><code>XMLConstants.XML_NS_URI</code> 318 319 * ("http://www.w3.org/XML/1998/namespace")</td> 320 321 * <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> 322 323 * </tr> 324 325 * <tr> 326 327 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> 328 329 * ("http://www.w3.org/2000/xmlns/")</td> 330 331 * <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> 332 333 * </tr> 334 335 * <tr> 336 337 * <td><code>null</code></td> 338 339 * <td><code>IllegalArgumentException</code> is thrown</td> 340 341 * </tr> 342 343 * </tbody> 344 345 * </table> 346 347 * 348 349 * @param namespaceURI URI of Namespace to lookup 350 351 * @return prefix bound to Namespace URI in current context 352 353 */ 354 355 String getPrefix(String namespaceURI); 356 357 358 359 /** 360 361 * Get all prefixes bound to a Namespace URI in the current scope. 362 363 * 364 365 * <p><strong>The returned <code>Iterator</code> is 366 367 * <em>not</em> modifiable. e.g. the 368 369 * <code>remove()</code> method will throw 370 371 * <code>UnsupportedOperationException</code>.</strong></p> 372 373 * 374 375 * <p>Prefixes are returned in an arbitrary, implementation 376 377 * dependent, order.</p> 378 379 * 380 381 * <p>When requesting prefixes by Namespace URI, the following 382 383 * table describes the returned prefixes value for all Namespace 384 385 * URI values:</p> 386 387 * 388 389 * <table border="2" rules="all" cellpadding="4"> 390 391 * <thead> 392 393 * <tr> 394 395 * <th align="center" colspan="2"><code> 396 397 * getPrefixes(namespaceURI)</code> return value for 398 399 * specified Namespace URIs</th> 400 401 * </tr> 402 403 * </thead> 404 405 * <tbody> 406 407 * <tr> 408 409 * <th>Namespace URI parameter</th> 410 411 * <th>prefixes value returned</th> 412 413 * </tr> 414 415 * <tr> 416 417 * <td>bound Namespace URI, 418 419 * including the <default Namespace URI></td> 420 421 * <td><code>Iterator</code> over prefixes bound to Namespace URI in 422 423 * the current scope in an arbitrary, implementation dependent, 424 425 * order</td> 426 427 * </tr> 428 429 * <tr> 430 431 * <td>unbound Namespace URI</td> 432 433 * <td>empty <code>Iterator</code></td> 434 435 * </tr> 436 437 * <tr> 438 439 * <td><code>XMLConstants.XML_NS_URI</code> 440 441 * ("http://www.w3.org/XML/1998/namespace")</td> 442 443 * <td><code>Iterator</code> with one element set to 444 445 * <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td> 446 447 * </tr> 448 449 * <tr> 450 451 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code> 452 453 * ("http://www.w3.org/2000/xmlns/")</td> 454 455 * <td><code>Iterator</code> with one element set to 456 457 * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td> 458 459 * </tr> 460 461 * <tr> 462 463 * <td><code>null</code></td> 464 465 * <td><code>IllegalArgumentException</code> is thrown</td> 466 467 * </tr> 468 469 * </tbody> 470 471 * </table> 472 473 * 474 475 * @param namespaceURI URI of Namespace to lookup 476 477 * @return <code>Iterator</code> for all prefixes bound to the 478 479 * Namespace URI in the current scope 480 481 */ 482 483 Iterator getPrefixes(String namespaceURI); 484 485 } 486