author | joehw |
Wed, 03 Jan 2018 18:21:10 -0800 | |
changeset 48429 | e9a564028f2f |
parent 48412 | d4412e380f6b |
permissions | -rw-r--r-- |
12005 | 1 |
/* |
48429
e9a564028f2f
8189704: broken links in the javax/xml/namespace package
joehw
parents:
48412
diff
changeset
|
2 |
* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved. |
12005 | 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. Oracle designates this |
|
8 |
* particular file as subject to the "Classpath" exception as provided |
|
9 |
* by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
24 |
*/ |
|
25 |
||
26 |
package javax.xml.namespace; |
|
27 |
||
28 |
import java.util.Iterator; |
|
29 |
||
30 |
/** |
|
29999 | 31 |
* Interface for read only XML Namespace context processing. |
12005 | 32 |
* |
29999 | 33 |
* <p>An XML Namespace has the properties: |
12005 | 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 |
|
29999 | 38 |
* following the {@code XMLConstants.XMLNS_ATTRIBUTE} |
12005 | 39 |
* ("xmlns") in the Namespace declaration</li> |
40 |
* </ul> |
|
41 |
* <p>example: |
|
29999 | 42 |
* {@code <element xmlns:prefix="http://Namespace-name-URI">} |
12005 | 43 |
* |
29999 | 44 |
* <p>All {@code get*(*)} methods operate in the current scope |
45 |
* for Namespace URI and prefix resolution. |
|
12005 | 46 |
* |
47 |
* <p>Note that a Namespace URI can be bound to |
|
48 |
* <strong>multiple</strong> prefixes in the current scope. This can |
|
29999 | 49 |
* occur when multiple {@code XMLConstants.XMLNS_ATTRIBUTE} |
12005 | 50 |
* ("xmlns") Namespace declarations occur in the same Start-Tag and |
29999 | 51 |
* refer to the same Namespace URI. e.g.<br> |
52 |
* <pre> {@code |
|
53 |
* <element xmlns:prefix1="http://Namespace-name-URI" |
|
54 |
* xmlns:prefix2="http://Namespace-name-URI"> } |
|
12005 | 55 |
* </pre> |
56 |
* This can also occur when the same Namespace URI is used in multiple |
|
29999 | 57 |
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns") Namespace |
58 |
* declarations in the logical parent element hierarchy. e.g.<br> |
|
59 |
* <pre> {@code |
|
60 |
* <parent xmlns:prefix1="http://Namespace-name-URI"> |
|
61 |
* <child xmlns:prefix2="http://Namespace-name-URI"> |
|
12005 | 62 |
* ... |
29999 | 63 |
* </child> |
64 |
* </parent> } |
|
65 |
* </pre> |
|
12005 | 66 |
* |
67 |
* <p>A prefix can only be bound to a <strong>single</strong> |
|
29999 | 68 |
* Namespace URI in the current scope. |
12005 | 69 |
* |
48412 | 70 |
* @author Jeff Suttor |
12005 | 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> |
|
48429
e9a564028f2f
8189704: broken links in the javax/xml/namespace package
joehw
parents:
48412
diff
changeset
|
75 |
* @see <a href="http://www.w3.org/TR/REC-xml-names/"> |
12005 | 76 |
* Namespaces in XML</a> |
77 |
* @since 1.5 |
|
78 |
*/ |
|
79 |
||
80 |
public interface NamespaceContext { |
|
81 |
||
82 |
/** |
|
29999 | 83 |
* Get Namespace URI bound to a prefix in the current scope. |
12005 | 84 |
* |
85 |
* <p>When requesting a Namespace URI by prefix, the following |
|
86 |
* table describes the returned Namespace URI value for all |
|
29999 | 87 |
* possible prefix values: |
12005 | 88 |
* |
45261 | 89 |
* <table class="striped"> |
90 |
* <caption>Return value for specified prefixes</caption> |
|
12005 | 91 |
* <thead> |
92 |
* <tr> |
|
45855 | 93 |
* <th scope="col">prefix parameter</th> |
94 |
* <th scope="col">Namespace URI return value</th> |
|
12005 | 95 |
* </tr> |
96 |
* </thead> |
|
97 |
* <tbody> |
|
98 |
* <tr> |
|
45855 | 99 |
* <th scope="row">{@code DEFAULT_NS_PREFIX} ("")</th> |
12005 | 100 |
* <td>default Namespace URI in the current scope or |
29999 | 101 |
* <code> {@link |
12005 | 102 |
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")} |
103 |
* </code> |
|
104 |
* when there is no default Namespace URI in the current scope</td> |
|
105 |
* </tr> |
|
106 |
* <tr> |
|
45855 | 107 |
* <th scope="row">bound prefix</th> |
12005 | 108 |
* <td>Namespace URI bound to prefix in current scope</td> |
109 |
* </tr> |
|
110 |
* <tr> |
|
45855 | 111 |
* <th scope="row">unbound prefix</th> |
12005 | 112 |
* <td> |
29999 | 113 |
* <code> {@link |
12005 | 114 |
* javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI("")} |
115 |
* </code> |
|
116 |
* </td> |
|
117 |
* </tr> |
|
118 |
* <tr> |
|
45855 | 119 |
* <th scope="row">{@code XMLConstants.XML_NS_PREFIX} ("xml")</th> |
29999 | 120 |
* <td>{@code XMLConstants.XML_NS_URI} |
12005 | 121 |
* ("http://www.w3.org/XML/1998/namespace")</td> |
122 |
* </tr> |
|
123 |
* <tr> |
|
45855 | 124 |
* <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</th> |
29999 | 125 |
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI} |
12005 | 126 |
* ("http://www.w3.org/2000/xmlns/")</td> |
127 |
* </tr> |
|
128 |
* <tr> |
|
45855 | 129 |
* <th scope="row">{@code null}</th> |
29999 | 130 |
* <td>{@code IllegalArgumentException} is thrown</td> |
12005 | 131 |
* </tr> |
132 |
* </tbody> |
|
133 |
* </table> |
|
134 |
* |
|
135 |
* @param prefix prefix to look up |
|
136 |
* |
|
137 |
* @return Namespace URI bound to prefix in the current scope |
|
138 |
* |
|
29999 | 139 |
* @throws IllegalArgumentException When {@code prefix} is |
140 |
* {@code null} |
|
12005 | 141 |
*/ |
142 |
String getNamespaceURI(String prefix); |
|
143 |
||
144 |
/** |
|
29999 | 145 |
* Get prefix bound to Namespace URI in the current scope. |
12005 | 146 |
* |
147 |
* <p>To get all prefixes bound to a Namespace URI in the current |
|
29999 | 148 |
* scope, use {@link #getPrefixes(String namespaceURI)}. |
12005 | 149 |
* |
150 |
* <p>When requesting a prefix by Namespace URI, the following |
|
151 |
* table describes the returned prefix value for all Namespace URI |
|
29999 | 152 |
* values: |
12005 | 153 |
* |
45261 | 154 |
* <table class="striped"> |
155 |
* <caption>Return value for specified Namespace URIs</caption> |
|
12005 | 156 |
* <thead> |
157 |
* <tr> |
|
45855 | 158 |
* <th scope="col">Namespace URI parameter</th> |
159 |
* <th scope="col">prefix value returned</th> |
|
12005 | 160 |
* </tr> |
161 |
* </thead> |
|
162 |
* <tbody> |
|
163 |
* <tr> |
|
45855 | 164 |
* <th scope="row">{@code <default Namespace URI>}</th> |
29999 | 165 |
* <td>{@code XMLConstants.DEFAULT_NS_PREFIX} ("") |
12005 | 166 |
* </td> |
167 |
* </tr> |
|
168 |
* <tr> |
|
45855 | 169 |
* <th scope="row">bound Namespace URI</th> |
12005 | 170 |
* <td>prefix bound to Namespace URI in the current scope, |
171 |
* if multiple prefixes are bound to the Namespace URI in |
|
172 |
* the current scope, a single arbitrary prefix, whose |
|
173 |
* choice is implementation dependent, is returned</td> |
|
174 |
* </tr> |
|
175 |
* <tr> |
|
45855 | 176 |
* <th scope="row">unbound Namespace URI</th> |
29999 | 177 |
* <td>{@code null}</td> |
12005 | 178 |
* </tr> |
179 |
* <tr> |
|
45855 | 180 |
* <th scope="row">{@code XMLConstants.XML_NS_URI} |
181 |
* ("http://www.w3.org/XML/1998/namespace")</th> |
|
29999 | 182 |
* <td>{@code XMLConstants.XML_NS_PREFIX} ("xml")</td> |
12005 | 183 |
* </tr> |
184 |
* <tr> |
|
45855 | 185 |
* <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI} |
186 |
* ("http://www.w3.org/2000/xmlns/")</th> |
|
29999 | 187 |
* <td>{@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td> |
12005 | 188 |
* </tr> |
189 |
* <tr> |
|
45855 | 190 |
* <th scope="row">{@code null}</th> |
29999 | 191 |
* <td>{@code IllegalArgumentException} is thrown</td> |
12005 | 192 |
* </tr> |
193 |
* </tbody> |
|
194 |
* </table> |
|
195 |
* |
|
196 |
* @param namespaceURI URI of Namespace to lookup |
|
197 |
* |
|
198 |
* @return prefix bound to Namespace URI in current context |
|
199 |
* |
|
29999 | 200 |
* @throws IllegalArgumentException When {@code namespaceURI} is |
201 |
* {@code null} |
|
12005 | 202 |
*/ |
203 |
String getPrefix(String namespaceURI); |
|
204 |
||
205 |
/** |
|
29999 | 206 |
* Get all prefixes bound to a Namespace URI in the current |
207 |
* scope. |
|
12005 | 208 |
* |
209 |
* <p>An Iterator over String elements is returned in an arbitrary, |
|
29999 | 210 |
* <strong>implementation dependent</strong>, order. |
12005 | 211 |
* |
29999 | 212 |
* <p><strong>The {@code Iterator} is |
12005 | 213 |
* <em>not</em> modifiable. e.g. the |
29999 | 214 |
* {@code remove()} method will throw |
215 |
* {@code UnsupportedOperationException}.</strong> |
|
12005 | 216 |
* |
217 |
* <p>When requesting prefixes by Namespace URI, the following |
|
218 |
* table describes the returned prefixes value for all Namespace |
|
29999 | 219 |
* URI values: |
12005 | 220 |
* |
45261 | 221 |
* <table class="striped"> |
222 |
* <caption>Return value for specified Namespace URIs</caption> |
|
12005 | 223 |
* <thead> |
224 |
* <tr> |
|
45855 | 225 |
* <th scope="col">Namespace URI parameter</th> |
226 |
* <th scope="col">prefixes value returned</th> |
|
12005 | 227 |
* </tr> |
228 |
* </thead> |
|
229 |
* <tbody> |
|
230 |
* <tr> |
|
45855 | 231 |
* <th scope="row">bound Namespace URI, |
232 |
* including the {@code <default Namespace URI>}</th> |
|
12005 | 233 |
* <td> |
29999 | 234 |
* {@code Iterator} over prefixes bound to Namespace URI in |
12005 | 235 |
* the current scope in an arbitrary, |
236 |
* <strong>implementation dependent</strong>, |
|
237 |
* order |
|
238 |
* </td> |
|
239 |
* </tr> |
|
240 |
* <tr> |
|
45855 | 241 |
* <th scope="row">unbound Namespace URI</th> |
29999 | 242 |
* <td>empty {@code Iterator}</td> |
12005 | 243 |
* </tr> |
244 |
* <tr> |
|
45855 | 245 |
* <th scope="row">{@code XMLConstants.XML_NS_URI} |
246 |
* ("http://www.w3.org/XML/1998/namespace")</th> |
|
29999 | 247 |
* <td>{@code Iterator} with one element set to |
248 |
* {@code XMLConstants.XML_NS_PREFIX} ("xml")</td> |
|
12005 | 249 |
* </tr> |
250 |
* <tr> |
|
45855 | 251 |
* <th scope="row">{@code XMLConstants.XMLNS_ATTRIBUTE_NS_URI} |
252 |
* ("http://www.w3.org/2000/xmlns/")</th> |
|
29999 | 253 |
* <td>{@code Iterator} with one element set to |
254 |
* {@code XMLConstants.XMLNS_ATTRIBUTE} ("xmlns")</td> |
|
12005 | 255 |
* </tr> |
256 |
* <tr> |
|
45855 | 257 |
* <th scope="row">{@code null}</th> |
29999 | 258 |
* <td>{@code IllegalArgumentException} is thrown</td> |
12005 | 259 |
* </tr> |
260 |
* </tbody> |
|
261 |
* </table> |
|
262 |
* |
|
263 |
* @param namespaceURI URI of Namespace to lookup |
|
264 |
* |
|
29999 | 265 |
* @return {@code Iterator} for all prefixes bound to the |
12005 | 266 |
* Namespace URI in the current scope |
267 |
* |
|
29999 | 268 |
* @throws IllegalArgumentException When {@code namespaceURI} is |
269 |
* {@code null} |
|
12005 | 270 |
*/ |
47359
e1a6c0168741
8181150: Fix lint warnings in JAXP repo: rawtypes and unchecked
joehw
parents:
47216
diff
changeset
|
271 |
Iterator<String> getPrefixes(String namespaceURI); |
12005 | 272 |
} |