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>&lt;element xmlns:prefix="http://Namespace-name-URI"&gt;</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     * &lt;element xmlns:prefix1="http://Namespace-name-URI"
062    
063     *          xmlns:prefix2="http://Namespace-name-URI"&gt;
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     * &lt;parent xmlns:prefix1="http://Namespace-name-URI">
076    
077     *   &lt;child xmlns:prefix2="http://Namespace-name-URI"&gt;
078    
079     *     ...
080    
081     *   &lt;/child&gt;
082    
083     * &lt;/parent&gt;
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>&lt;default Namespace URI&gt;</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 &lt;default Namespace URI&gt;</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