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