0
|
1 //$Id: QName.java,v 1.10 2004/02/09 23:41:21 jsuttor Exp $
|
|
2
|
|
3 /*
|
|
4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
|
|
5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
6 */
|
|
7
|
|
8 package javax.xml.namespace;
|
|
9
|
|
10 import java.io.Serializable;
|
|
11
|
|
12 import javax.xml.XMLConstants;
|
|
13
|
|
14 /**
|
|
15 * <p><code>QName</code> represents a <strong>qualified name</strong>
|
|
16 * as defined in the XML specifications: <a
|
|
17 * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
|
|
18 * Datatypes specification</a>, <a
|
|
19 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
|
|
20 * in XML</a>, <a
|
|
21 * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
|
|
22 * in XML Errata</a>.</p>
|
|
23 *
|
|
24 * <p>The value of a <code>QName</code> contains a <strong>Namespace
|
|
25 * URI</strong>, <strong>local part</strong> and
|
|
26 * <strong>prefix</strong>.</p>
|
|
27 *
|
|
28 * <p>The prefix is included in <code>QName</code> to retain lexical
|
|
29 * information <strong><em>when present</em></strong> in an {@link
|
|
30 * javax.xml.transform.Source XML input source}. The prefix is
|
|
31 * <strong><em>NOT</em></strong> used in {@link #equals(Object)
|
|
32 * QName.equals(Object)} or to compute the {@link #hashCode()
|
|
33 * QName.hashCode()}. Equality and the hash code are defined using
|
|
34 * <strong><em>only</em></strong> the Namespace URI and local part.</p>
|
|
35 *
|
|
36 * <p>If not specified, the Namespace URI is set to {@link
|
|
37 * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
|
|
38 * If not specified, the prefix is set to {@link
|
|
39 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
|
|
40 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
|
|
41 *
|
|
42 * <p><code>QName</code> is immutable.</p>
|
|
43 *
|
|
44 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
|
|
45 * @version $Revision: 1.10 $, $Date: 2004/02/09 23:41:21 $
|
|
46 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2: Datatypes specification</a>
|
|
47 * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces in XML</a>
|
|
48 * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces in XML Errata</a>
|
|
49 * @since 1.5
|
|
50 */
|
|
51
|
|
52 public class QName implements Serializable {
|
|
53
|
|
54 /**
|
|
55 * <p>Stream Unique Identifier.</p>
|
|
56 */
|
|
57 private static final long serialVersionUID = 4418622981026545151L;
|
|
58
|
|
59 /**
|
|
60 * <p>Namespace URI of this <code>QName</code>.</p>
|
|
61 */
|
|
62 private final String namespaceURI;
|
|
63
|
|
64 /**
|
|
65 * <p>local part of this <code>QName</code>.</p>
|
|
66 */
|
|
67 private final String localPart;
|
|
68
|
|
69 /**
|
|
70 * <p>prefix of this <code>QName</code>.</p>
|
|
71 */
|
|
72 private final String prefix;
|
|
73
|
|
74 /**
|
|
75 * <p><code>QName</code> constructor specifying the Namespace URI
|
|
76 * and local part.</p>
|
|
77 *
|
|
78 * <p>If the Namespace URI is <code>null</code>, it is set to
|
|
79 * {@link javax.xml.XMLConstants#NULL_NS_URI
|
|
80 * XMLConstants.NULL_NS_URI}. This value represents no
|
|
81 * explicitly defined Namespace as defined by the <a
|
|
82 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
|
|
83 * in XML</a> specification. This action preserves compatible
|
|
84 * behavior with QName 1.0. Explicitly providing the {@link
|
|
85 * javax.xml.XMLConstants#NULL_NS_URI
|
|
86 * XMLConstants.NULL_NS_URI} value is the preferred coding
|
|
87 * style.</p>
|
|
88 *
|
|
89 * <p>If the local part is <code>null</code> an
|
|
90 * <code>IllegalArgumentException</code> is thrown.
|
|
91 * A local part of "" is allowed to preserve
|
|
92 * compatible behavior with QName 1.0. </p>
|
|
93 *
|
|
94 * <p>When using this constructor, the prefix is set to {@link
|
|
95 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
|
|
96 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
|
|
97 *
|
|
98 * <p>The Namespace URI is not validated as a
|
|
99 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
|
|
100 * The local part is not validated as a
|
|
101 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
|
|
102 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
|
|
103 * in XML</a>.</p>
|
|
104 *
|
|
105 * @param namespaceURI Namespace URI of the <code>QName</code>
|
|
106 * @param localPart local part of the <code>QName</code>
|
|
107 *
|
|
108 * @see #QName(String namespaceURI, String localPart, String
|
|
109 * prefix) QName(String namespaceURI, String localPart, String
|
|
110 * prefix)
|
|
111 */
|
|
112 public QName(final String namespaceURI, final String localPart) {
|
|
113 this(namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX);
|
|
114 }
|
|
115
|
|
116 /**
|
|
117 * <p><code>QName</code> constructor specifying the Namespace URI,
|
|
118 * local part and prefix.</p>
|
|
119 *
|
|
120 * <p>If the Namespace URI is <code>null</code>, it is set to
|
|
121 * {@link javax.xml.XMLConstants#NULL_NS_URI
|
|
122 * XMLConstants.NULL_NS_URI}. This value represents no
|
|
123 * explicitly defined Namespace as defined by the <a
|
|
124 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
|
|
125 * in XML</a> specification. This action preserves compatible
|
|
126 * behavior with QName 1.0. Explicitly providing the {@link
|
|
127 * javax.xml.XMLConstants#NULL_NS_URI
|
|
128 * XMLConstants.NULL_NS_URI} value is the preferred coding
|
|
129 * style.</p>
|
|
130 *
|
|
131 * <p>If the local part is <code>null</code> an
|
|
132 * <code>IllegalArgumentException</code> is thrown.
|
|
133 * A local part of "" is allowed to preserve
|
|
134 * compatible behavior with QName 1.0. </p>
|
|
135 *
|
|
136 * <p>If the prefix is <code>null</code>, an
|
|
137 * <code>IllegalArgumentException</code> is thrown. Use {@link
|
|
138 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
|
|
139 * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no
|
|
140 * prefix is present or the prefix is not relevant.</p>
|
|
141 *
|
|
142 * <p>The Namespace URI is not validated as a
|
|
143 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
|
|
144 * The local part and prefix are not validated as a
|
|
145 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
|
|
146 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
|
|
147 * in XML</a>.</p>
|
|
148 *
|
|
149 * @param namespaceURI Namespace URI of the <code>QName<code>
|
|
150 * @param localPart local part of the <code>QName<code>
|
|
151 * @param prefix prefix of the <code>QName<code>
|
|
152 */
|
|
153 public QName(String namespaceURI, String localPart, String prefix) {
|
|
154
|
|
155 // map null Namespace URI to default to preserve compatibility with QName 1.0
|
|
156 if (namespaceURI == null) {
|
|
157 this.namespaceURI = XMLConstants.NULL_NS_URI;
|
|
158 } else {
|
|
159 this.namespaceURI = namespaceURI;
|
|
160 }
|
|
161
|
|
162 // local part is required. "" is allowed to preserve compatibility with QName 1.0
|
|
163 if (localPart == null) {
|
|
164 throw new IllegalArgumentException("local part cannot be \"null\" when creating a QName");
|
|
165 }
|
|
166 this.localPart = localPart;
|
|
167
|
|
168 // prefix is required
|
|
169 if (prefix == null) {
|
|
170 throw new IllegalArgumentException("prefix cannot be \"null\" when creating a QName");
|
|
171 }
|
|
172 this.prefix = prefix;
|
|
173 }
|
|
174
|
|
175 /**
|
|
176 * <p><code>QName</code> constructor specifying the local part.</p>
|
|
177 *
|
|
178 * <p>If the local part is <code>null</code> an
|
|
179 * <code>IllegalArgumentException</code> is thrown.
|
|
180 * A local part of "" is allowed to preserve
|
|
181 * compatible behavior with QName 1.0. </p>
|
|
182 *
|
|
183 * <p>When using this constructor, the Namespace URI is set to
|
|
184 * {@link javax.xml.XMLConstants#NULL_NS_URI
|
|
185 * XMLConstants.NULL_NS_URI} and the prefix is set to {@link
|
|
186 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
|
|
187 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
|
|
188 *
|
|
189 * <p><em>In an XML context, all Element and Attribute names exist
|
|
190 * in the context of a Namespace. Making this explicit during the
|
|
191 * construction of a <code>QName</code> helps prevent hard to
|
|
192 * diagnosis XML validity errors. The constructors {@link
|
|
193 * #QName(String namespaceURI, String localPart) QName(String
|
|
194 * namespaceURI, String localPart)} and
|
|
195 * {@link #QName(String namespaceURI, String localPart, String prefix)}
|
|
196 * are preferred.</em></p>
|
|
197 *
|
|
198 * <p>The local part is not validated as a
|
|
199 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
|
|
200 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
|
|
201 * in XML</a>.</p>
|
|
202 *
|
|
203 * @param localPart local part of the <code>QName</code>
|
|
204 * @see #QName(String namespaceURI, String localPart) QName(String
|
|
205 * namespaceURI, String localPart)
|
|
206 * @see #QName(String namespaceURI, String localPart, String
|
|
207 * prefix) QName(String namespaceURI, String localPart, String
|
|
208 * prefix)
|
|
209 */
|
|
210 public QName(String localPart) {
|
|
211 this(
|
|
212 XMLConstants.NULL_NS_URI,
|
|
213 localPart,
|
|
214 XMLConstants.DEFAULT_NS_PREFIX);
|
|
215 }
|
|
216
|
|
217 /**
|
|
218 * <p>Get the Namespace URI of this <code>QName</code>.</p>
|
|
219 *
|
|
220 * @return Namespace URI of this <code>QName</code>
|
|
221 */
|
|
222 public String getNamespaceURI() {
|
|
223 return namespaceURI;
|
|
224 }
|
|
225
|
|
226 /**
|
|
227 * <p>Get the local part of this <code>QName</code>.</p>
|
|
228 *
|
|
229 * @return local part of this <code>QName</code>
|
|
230 */
|
|
231 public String getLocalPart() {
|
|
232 return localPart;
|
|
233 }
|
|
234
|
|
235 /**
|
|
236 * <p>Get the prefix of this <code>QName</code>.</p>
|
|
237 *
|
|
238 * <p>The prefix assigned to a <code>QName</code> might
|
|
239 * <strong><em>NOT</em></strong> be valid in a different
|
|
240 * context. For example, a <code>QName</code> may be assigned a
|
|
241 * prefix in the context of parsing a document but that prefix may
|
|
242 * be invalid in the context of a different document.</p>
|
|
243 *
|
|
244 * @return prefix of this <code>QName</code>
|
|
245 */
|
|
246 public String getPrefix() {
|
|
247 return prefix;
|
|
248 }
|
|
249
|
|
250 /**
|
|
251 * <p>Test this <code>QName</code> for equality with another
|
|
252 * <code>Object</code>.</p>
|
|
253 *
|
|
254 * <p>If the <code>Object</code> to be tested is not a
|
|
255 * <code>QName</code> or is <code>null</code>, then this method
|
|
256 * returns <code>false</code>.</p>
|
|
257 *
|
|
258 * <p>Two <code>QName</code>s are considered equal if and only if
|
|
259 * both the Namespace URI and local part are equal. This method
|
|
260 * uses <code>String.equals()</code> to check equality of the
|
|
261 * Namespace URI and local part. The prefix is
|
|
262 * <strong><em>NOT</em></strong> used to determine equality.</p>
|
|
263 *
|
|
264 * <p>This method satisfies the general contract of {@link
|
|
265 * java.lang.Object#equals(Object) Object.equals(Object)}</p>
|
|
266 *
|
|
267 * @param objectToTest the <code>Object</code> to test for
|
|
268 * equality with this <code>QName</code>
|
|
269 * @return <code>true</code> if the given <code>Object</code> is
|
|
270 * equal to this <code>QName</code> else <code>false</code>
|
|
271 */
|
|
272 public final boolean equals(Object objectToTest) {
|
|
273 if (objectToTest == null || !(objectToTest instanceof QName)) {
|
|
274 return false;
|
|
275 }
|
|
276
|
|
277 QName qName = (QName) objectToTest;
|
|
278
|
|
279 return namespaceURI.equals(qName.namespaceURI)
|
|
280 && localPart.equals(qName.localPart);
|
|
281 }
|
|
282
|
|
283 /**
|
|
284 * <p>Generate the hash code for this <code>QName</code>.</p>
|
|
285 *
|
|
286 * <p>The hash code is calculated using both the Namespace URI and
|
|
287 * the local part of the <code>QName</code>. The prefix is
|
|
288 * <strong><em>NOT</em></strong> used to calculate the hash
|
|
289 * code.</p>
|
|
290 *
|
|
291 * <p>This method satisfies the general contract of {@link
|
|
292 * java.lang.Object#hashCode() Object.hashCode()}.</p>
|
|
293 *
|
|
294 * @return hash code for this <code>QName</code> <code>Object</code>
|
|
295 */
|
|
296 public final int hashCode() {
|
|
297 return namespaceURI.hashCode() ^ localPart.hashCode();
|
|
298 }
|
|
299
|
|
300 /**
|
|
301 * <p><code>String</code> representation of this
|
|
302 * <code>QName</code>.</p>
|
|
303 *
|
|
304 * <p>The commonly accepted way of representing a <code>QName</code>
|
|
305 * as a <code>String</code> was <a href="http://jclark.com/xml/xmlns.htm">defined</a>
|
|
306 * by James Clark. Although this is not a <em>standard</em>
|
|
307 * specification, it is in common use, e.g. {@link javax.xml.transform.Transformer#setParameter(String name, Object value)}.
|
|
308 * This implementation represents a <code>QName</code> as:
|
|
309 * "{" + Namespace URI + "}" + local part. If the Namespace URI
|
|
310 * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
|
|
311 * local part is returned. An appropriate use of this method is
|
|
312 * for debugging or logging for human consumption.</p>
|
|
313 *
|
|
314 * <p>Note the prefix value is <strong><em>NOT</em></strong>
|
|
315 * returned as part of the <code>String</code> representation.</p>
|
|
316 *
|
|
317 * <p>This method satisfies the general contract of {@link
|
|
318 * java.lang.Object#toString() Object.toString()}.</p>
|
|
319 *
|
|
320 * @return <code>String</code> representation of this <code>QName</code>
|
|
321 */
|
|
322 public String toString() {
|
|
323 if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
|
|
324 return localPart;
|
|
325 } else {
|
|
326 return "{" + namespaceURI + "}" + localPart;
|
|
327 }
|
|
328 }
|
|
329
|
|
330 /**
|
|
331 * <p><code>QName</code> derived from parsing the formatted
|
|
332 * <code>String</code>.</p>
|
|
333 *
|
|
334 * <p>If the <code>String</code> is <code>null</code> or does not conform to
|
|
335 * {@link #toString() QName.toString()} formatting, an
|
|
336 * <code>IllegalArgumentException</code> is thrown.</p>
|
|
337 *
|
|
338 * <p><em>The <code>String</code> <strong>MUST</strong> be in the
|
|
339 * form returned by {@link #toString() QName.toString()}.</em></p>
|
|
340
|
|
341 * <p>The commonly accepted way of representing a <code>QName</code>
|
|
342 * as a <code>String</code> was <a href="http://jclark.com/xml/xmlns.htm">defined</a>
|
|
343 * by James Clark. Although this is not a <em>standard</em>
|
|
344 * specification, it is in common use, e.g. {@link javax.xml.transform.Transformer#setParameter(String name, Object value)}.
|
|
345 * This implementation parses a <code>String</code> formatted
|
|
346 * as: "{" + Namespace URI + "}" + local part. If the Namespace
|
|
347 * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
|
|
348 * local part should be provided.</p>
|
|
349 *
|
|
350 * <p>The prefix value <strong><em>CANNOT</em></strong> be
|
|
351 * represented in the <code>String</code> and will be set to
|
|
352 * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
|
|
353 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
|
|
354 *
|
|
355 * <p>This method does not do full validation of the resulting
|
|
356 * <code>QName</code>.
|
|
357 * <p>The Namespace URI is not validated as a
|
|
358 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
|
|
359 * The local part is not validated as a
|
|
360 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
|
|
361 * as specified in
|
|
362 * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
|
|
363 *
|
|
364 * @param qNameAsString <code>String</code> representation
|
|
365 * of the <code>QName</code>
|
|
366 * @return <code>QName</code> corresponding to the given <code>String</code>
|
|
367 * @see #toString() QName.toString()
|
|
368 */
|
|
369 public static QName valueOf(String qNameAsString) {
|
|
370
|
|
371 // null is not valid
|
|
372 if (qNameAsString == null) {
|
|
373 throw new IllegalArgumentException("cannot create QName from \"null\" or \"\" String");
|
|
374 }
|
|
375
|
|
376 // "" local part is valid to preserve compatible behavior with QName 1.0
|
|
377 if (qNameAsString.length() == 0) {
|
|
378 return new QName(
|
|
379 XMLConstants.NULL_NS_URI,
|
|
380 qNameAsString,
|
|
381 XMLConstants.DEFAULT_NS_PREFIX);
|
|
382 }
|
|
383
|
|
384 // local part only?
|
|
385 if (qNameAsString.charAt(0) != '{') {
|
|
386 return new QName(
|
|
387 XMLConstants.NULL_NS_URI,
|
|
388 qNameAsString,
|
|
389 XMLConstants.DEFAULT_NS_PREFIX);
|
|
390 }
|
|
391
|
|
392 // Namespace URI improperly specified?
|
|
393 if (qNameAsString.startsWith("{" + XMLConstants.NULL_NS_URI + "}")) {
|
|
394 throw new IllegalArgumentException(
|
|
395 "Namespace URI .equals(XMLConstants.NULL_NS_URI), "
|
|
396 + ".equals(\"" + XMLConstants.NULL_NS_URI + "\"), "
|
|
397 + "only the local part, "
|
|
398 + "\"" + qNameAsString.substring(2 + XMLConstants.NULL_NS_URI.length()) + "\", "
|
|
399 + "should be provided.");
|
|
400 }
|
|
401
|
|
402 // Namespace URI and local part specified
|
|
403 int endOfNamespaceURI = qNameAsString.indexOf('}');
|
|
404 if (endOfNamespaceURI == -1) {
|
|
405 throw new IllegalArgumentException(
|
|
406 "cannot create QName from \""
|
|
407 + qNameAsString
|
|
408 + "\", missing closing \"}\"");
|
|
409 }
|
|
410 return new QName(
|
|
411 qNameAsString.substring(1, endOfNamespaceURI),
|
|
412 qNameAsString.substring(endOfNamespaceURI + 1),
|
|
413 XMLConstants.DEFAULT_NS_PREFIX);
|
|
414 }
|
|
415 }
|