1 /*
2 * Copyright 2003-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.xml.namespace;
27
28 import java.util.Iterator;
29
30 /**
31 * <p>Interface for read only XML Namespace context processing.</p>
32 *
33 * <p>An XML Namespace has the properties:</p>
34 * <ul>
35 * <li>Namespace URI:
36 * Namespace name expressed as a URI to which the prefix is bound</li>
37 * <li>prefix: syntactically, this is the part of the attribute name
38 * following the <code>XMLConstants.XMLNS_ATTRIBUTE</code>
39 * ("xmlns") in the Namespace declaration</li>
40 * </ul>
41 * <p>example:
42 * <code><element xmlns:prefix="http://Namespace-name-URI"></code></p>
43 *
44 * <p>All <code>get*(*)</code> methods operate in the current scope
45 * for Namespace URI and prefix resolution.</p>
46 *
47 * <p>Note that a Namespace URI can be bound to
48 * <strong>multiple</strong> prefixes in the current scope. This can
49 * occur when multiple <code>XMLConstants.XMLNS_ATTRIBUTE</code>
50 * ("xmlns") Namespace declarations occur in the same Start-Tag and
51 * refer to the same Namespace URI. e.g.<br />
52 * <pre>
53 * <element xmlns:prefix1="http://Namespace-name-URI"
54 * xmlns:prefix2="http://Namespace-name-URI">
55 * </pre>
56 * This can also occur when the same Namespace URI is used in multiple
57 * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns") Namespace
58 * declarations in the logical parent element hierarchy. e.g.<br />
59 * <pre>
60 * <parent xmlns:prefix1="http://Namespace-name-URI">
61 * <child xmlns:prefix2="http://Namespace-name-URI">
62 * ...
63 * </child>
64 * </parent>
65 * </pre></p>
66 *
67 * <p>A prefix can only be bound to a <strong>single</strong>
68 * Namespace URI in the current scope.</p>
69 *
70 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
71 * @see javax.xml.XMLConstants
72 * javax.xml.XMLConstants for declarations of common XML values
73 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
74 * XML Schema Part2: Datatypes</a>
75 * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
76 * Namespaces in XML</a>
77 * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">
78 * Namespaces in XML Errata</a>
79 * @since 1.5
80 */
81
82 public interface NamespaceContext {
83
84 /**
85 * <p>Get Namespace URI bound to a prefix in the current scope.</p>
86 *
87 * <p>When requesting a Namespace URI by prefix, the following
88 * table describes the returned Namespace URI value for all
89 * possible prefix values:</p>
90 *
91 * <table border="2" rules="all" cellpadding="4">
92 * <thead>
93 * <tr>
94 * <td align="center" colspan="2">
95 * <code>getNamespaceURI(prefix)</code>
96 * return value for specified prefixes
97 * </td>
98 * </tr>
99 * <tr>
100 * <td>prefix parameter</td>
101 * <td>Namespace URI return value</td>
102 * </tr>
103 * </thead>
104 * <tbody>
105 * <tr>
106 * <td><code>DEFAULT_NS_PREFIX</code> ("")</td>
107 * <td>default Namespace URI in the current scope or
108 * <code>{@link
109 * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
110 * </code>
111 * when there is no default Namespace URI in the current scope</td>
112 * </tr>
113 * <tr>
114 * <td>bound prefix</td>
115 * <td>Namespace URI bound to prefix in current scope</td>
116 * </tr>
117 * <tr>
118 * <td>unbound prefix</td>
119 * <td>
120 * <code>{@link
121 * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")}
122 * </code>
123 * </td>
124 * </tr>
125 * <tr>
126 * <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
127 * <td><code>XMLConstants.XML_NS_URI</code>
128 * ("http://www.w3.org/XML/1998/namespace")</td>
129 * </tr>
130 * <tr>
131 * <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
132 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
133 * ("http://www.w3.org/2000/xmlns/")</td>
134 * </tr>
135 * <tr>
136 * <td><code>null</code></td>
137 * <td><code>IllegalArgumentException</code> is thrown</td>
138 * </tr>
139 * </tbody>
140 * </table>
141 *
142 * @param prefix prefix to look up
143 *
144 * @return Namespace URI bound to prefix in the current scope
145 *
146 * @throws IllegalArgumentException When <code>prefix</code> is
147 * <code>null</code>
148 */
149 String getNamespaceURI(String prefix);
150
151 /**
152 * <p>Get prefix bound to Namespace URI in the current scope.</p>
153 *
154 * <p>To get all prefixes bound to a Namespace URI in the current
155 * scope, use {@link #getPrefixes(String namespaceURI)}.</p>
156 *
157 * <p>When requesting a prefix by Namespace URI, the following
158 * table describes the returned prefix value for all Namespace URI
159 * values:</p>
160 *
161 * <table border="2" rules="all" cellpadding="4">
162 * <thead>
163 * <tr>
164 * <th align="center" colspan="2">
165 * <code>getPrefix(namespaceURI)</code> return value for
166 * specified Namespace URIs
167 * </th>
168 * </tr>
169 * <tr>
170 * <th>Namespace URI parameter</th>
171 * <th>prefix value returned</th>
172 * </tr>
173 * </thead>
174 * <tbody>
175 * <tr>
176 * <td><default Namespace URI></td>
177 * <td><code>XMLConstants.DEFAULT_NS_PREFIX</code> ("")
178 * </td>
179 * </tr>
180 * <tr>
181 * <td>bound Namespace URI</td>
182 * <td>prefix bound to Namespace URI in the current scope,
183 * if multiple prefixes are bound to the Namespace URI in
184 * the current scope, a single arbitrary prefix, whose
185 * choice is implementation dependent, is returned</td>
186 * </tr>
187 * <tr>
188 * <td>unbound Namespace URI</td>
189 * <td><code>null</code></td>
190 * </tr>
191 * <tr>
192 * <td><code>XMLConstants.XML_NS_URI</code>
193 * ("http://www.w3.org/XML/1998/namespace")</td>
194 * <td><code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
195 * </tr>
196 * <tr>
197 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
198 * ("http://www.w3.org/2000/xmlns/")</td>
199 * <td><code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
200 * </tr>
201 * <tr>
202 * <td><code>null</code></td>
203 * <td><code>IllegalArgumentException</code> is thrown</td>
204 * </tr>
205 * </tbody>
206 * </table>
207 *
208 * @param namespaceURI URI of Namespace to lookup
209 *
210 * @return prefix bound to Namespace URI in current context
211 *
212 * @throws IllegalArgumentException When <code>namespaceURI</code> is
213 * <code>null</code>
214 */
215 String getPrefix(String namespaceURI);
216
217 /**
218 * <p>Get all prefixes bound to a Namespace URI in the current
219 * scope.</p>
220 *
221 * <p>An Iterator over String elements is returned in an arbitrary,
222 * <strong>implementation dependent</strong>, order.</p>
223 *
224 * <p><strong>The <code>Iterator</code> is
225 * <em>not</em> modifiable. e.g. the
226 * <code>remove()</code> method will throw
227 * <code>UnsupportedOperationException</code>.</strong></p>
228 *
229 * <p>When requesting prefixes by Namespace URI, the following
230 * table describes the returned prefixes value for all Namespace
231 * URI values:</p>
232 *
233 * <table border="2" rules="all" cellpadding="4">
234 * <thead>
235 * <tr>
236 * <th align="center" colspan="2"><code>
237 * getPrefixes(namespaceURI)</code> return value for
238 * specified Namespace URIs</th>
239 * </tr>
240 * <tr>
241 * <th>Namespace URI parameter</th>
242 * <th>prefixes value returned</th>
243 * </tr>
244 * </thead>
245 * <tbody>
246 * <tr>
247 * <td>bound Namespace URI,
248 * including the <default Namespace URI></td>
249 * <td>
250 * <code>Iterator</code> over prefixes bound to Namespace URI in
251 * the current scope in an arbitrary,
252 * <strong>implementation dependent</strong>,
253 * order
254 * </td>
255 * </tr>
256 * <tr>
257 * <td>unbound Namespace URI</td>
258 * <td>empty <code>Iterator</code></td>
259 * </tr>
260 * <tr>
261 * <td><code>XMLConstants.XML_NS_URI</code>
262 * ("http://www.w3.org/XML/1998/namespace")</td>
263 * <td><code>Iterator</code> with one element set to
264 * <code>XMLConstants.XML_NS_PREFIX</code> ("xml")</td>
265 * </tr>
266 * <tr>
267 * <td><code>XMLConstants.XMLNS_ATTRIBUTE_NS_URI</code>
268 * ("http://www.w3.org/2000/xmlns/")</td>
269 * <td><code>Iterator</code> with one element set to
270 * <code>XMLConstants.XMLNS_ATTRIBUTE</code> ("xmlns")</td>
271 * </tr>
272 * <tr>
273 * <td><code>null</code></td>
274 * <td><code>IllegalArgumentException</code> is thrown</td>
275 * </tr>
276 * </tbody>
277 * </table>
278 *
279 * @param namespaceURI URI of Namespace to lookup
280 *
281 * @return <code>Iterator</code> for all prefixes bound to the
282 * Namespace URI in the current scope
283 *
284 * @throws IllegalArgumentException When <code>namespaceURI</code> is
285 * <code>null</code>
286 */
287 Iterator getPrefixes(String namespaceURI);
288 }
Save This Page