1 /*
2 * Copyright (c) 2003, 2006, Oracle and/or its affiliates. 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. 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.io.Serializable;
29 import java.security.AccessController;
30 import java.security.PrivilegedAction;
31
32 import javax.xml.XMLConstants;
33
34 /**
35 * <p><code>QName</code> represents a <strong>qualified name</strong>
36 * as defined in the XML specifications: <a
37 * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
38 * Datatypes specification</a>, <a
39 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
40 * in XML</a>, <a
41 * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
42 * in XML Errata</a>.</p>
43 *
44 * <p>The value of a <code>QName</code> contains a <strong>Namespace
45 * URI</strong>, <strong>local part</strong> and
46 * <strong>prefix</strong>.</p>
47 *
48 * <p>The prefix is included in <code>QName</code> to retain lexical
49 * information <strong><em>when present</em></strong> in an {@link
50 * javax.xml.transform.Source XML input source}. The prefix is
51 * <strong><em>NOT</em></strong> used in {@link #equals(Object)
52 * QName.equals(Object)} or to compute the {@link #hashCode()
53 * QName.hashCode()}. Equality and the hash code are defined using
54 * <strong><em>only</em></strong> the Namespace URI and local part.</p>
55 *
56 * <p>If not specified, the Namespace URI is set to {@link
57 * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
58 * If not specified, the prefix is set to {@link
59 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
60 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
61 *
62 * <p><code>QName</code> is immutable.</p>
63 *
64 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
65 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
66 * XML Schema Part2: Datatypes specification</a>
67 * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
68 * Namespaces in XML</a>
69 * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">
70 * Namespaces in XML Errata</a>
71 * @since 1.5
72 */
73
74 public class QName implements Serializable {
75
76 /**
77 * <p>Stream Unique Identifier.</p>
78 *
79 * <p>Due to a historical defect, QName was released with multiple
80 * serialVersionUID values even though its serialization was the
81 * same.</p>
82 *
83 * <p>To workaround this issue, serialVersionUID is set with either
84 * a default value or a compatibility value. To use the
85 * compatiblity value, set the system property:</p>
86 *
87 * <code>com.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0</code>
88 *
89 * <p>This workaround was inspired by classes in the javax.management
90 * package, e.g. ObjectName, etc.
91 * See CR6267224 for original defect report.</p>
92 */
93 private static final long serialVersionUID;
94 /**
95 * <p>Default <code>serialVersionUID</code> value.</p>
96 */
97 private static final long defaultSerialVersionUID = -9120448754896609940L;
98 /**
99 * <p>Compatibility <code>serialVersionUID</code> value.</p>
100 */
101 private static final long compatibleSerialVersionUID = 4418622981026545151L;
102 /**
103 * <p>Flag to use default or campatible serialVersionUID.</p>
104 */
105 private static boolean useDefaultSerialVersionUID = true;
106 static {
107 try {
108 // use a privileged block as reading a system property
109 String valueUseCompatibleSerialVersionUID = (String) AccessController.doPrivileged(
110 new PrivilegedAction() {
111 public Object run() {
112 return System.getProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID");
113 }
114 }
115 );
116 useDefaultSerialVersionUID = (valueUseCompatibleSerialVersionUID != null && valueUseCompatibleSerialVersionUID.equals("1.0")) ? false : true;
117 } catch (Exception exception) {
118 // use default if any Exceptions
119 useDefaultSerialVersionUID = true;
120 }
121
122 // set serialVersionUID to desired value
123 if (useDefaultSerialVersionUID) {
124 serialVersionUID = defaultSerialVersionUID;
125 } else {
126 serialVersionUID = compatibleSerialVersionUID;
127 }
128 }
129
130 /**
131 * <p>Namespace URI of this <code>QName</code>.</p>
132 */
133 private final String namespaceURI;
134
135 /**
136 * <p>local part of this <code>QName</code>.</p>
137 */
138 private final String localPart;
139
140 /**
141 * <p>prefix of this <code>QName</code>.</p>
142 */
143 private final String prefix;
144
145 /**
146 * <p><code>QName</code> constructor specifying the Namespace URI
147 * and local part.</p>
148 *
149 * <p>If the Namespace URI is <code>null</code>, it is set to
150 * {@link javax.xml.XMLConstants#NULL_NS_URI
151 * XMLConstants.NULL_NS_URI}. This value represents no
152 * explicitly defined Namespace as defined by the <a
153 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
154 * in XML</a> specification. This action preserves compatible
155 * behavior with QName 1.0. Explicitly providing the {@link
156 * javax.xml.XMLConstants#NULL_NS_URI
157 * XMLConstants.NULL_NS_URI} value is the preferred coding
158 * style.</p>
159 *
160 * <p>If the local part is <code>null</code> an
161 * <code>IllegalArgumentException</code> is thrown.
162 * A local part of "" is allowed to preserve
163 * compatible behavior with QName 1.0. </p>
164 *
165 * <p>When using this constructor, the prefix is set to {@link
166 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
167 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
168 *
169 * <p>The Namespace URI is not validated as a
170 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
171 * The local part is not validated as a
172 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
173 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
174 * in XML</a>.</p>
175 *
176 * @param namespaceURI Namespace URI of the <code>QName</code>
177 * @param localPart local part of the <code>QName</code>
178 *
179 * @throws IllegalArgumentException When <code>localPart</code> is
180 * <code>null</code>
181 *
182 * @see #QName(String namespaceURI, String localPart, String
183 * prefix) QName(String namespaceURI, String localPart, String
184 * prefix)
185 */
186 public QName(final String namespaceURI, final String localPart) {
187 this(namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX);
188 }
189
190 /**
191 * <p><code>QName</code> constructor specifying the Namespace URI,
192 * local part and prefix.</p>
193 *
194 * <p>If the Namespace URI is <code>null</code>, it is set to
195 * {@link javax.xml.XMLConstants#NULL_NS_URI
196 * XMLConstants.NULL_NS_URI}. This value represents no
197 * explicitly defined Namespace as defined by the <a
198 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
199 * in XML</a> specification. This action preserves compatible
200 * behavior with QName 1.0. Explicitly providing the {@link
201 * javax.xml.XMLConstants#NULL_NS_URI
202 * XMLConstants.NULL_NS_URI} value is the preferred coding
203 * style.</p>
204 *
205 * <p>If the local part is <code>null</code> an
206 * <code>IllegalArgumentException</code> is thrown.
207 * A local part of "" is allowed to preserve
208 * compatible behavior with QName 1.0. </p>
209 *
210 * <p>If the prefix is <code>null</code>, an
211 * <code>IllegalArgumentException</code> is thrown. Use {@link
212 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
213 * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no
214 * prefix is present or the prefix is not relevant.</p>
215 *
216 * <p>The Namespace URI is not validated as a
217 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
218 * The local part and prefix are not validated as a
219 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
220 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
221 * in XML</a>.</p>
222 *
223 * @param namespaceURI Namespace URI of the <code>QName</code>
224 * @param localPart local part of the <code>QName</code>
225 * @param prefix prefix of the <code>QName</code>
226 *
227 * @throws IllegalArgumentException When <code>localPart</code>
228 * or <code>prefix</code> is <code>null</code>
229 */
230 public QName(String namespaceURI, String localPart, String prefix) {
231
232 // map null Namespace URI to default
233 // to preserve compatibility with QName 1.0
234 if (namespaceURI == null) {
235 this.namespaceURI = XMLConstants.NULL_NS_URI;
236 } else {
237 this.namespaceURI = namespaceURI;
238 }
239
240 // local part is required.
241 // "" is allowed to preserve compatibility with QName 1.0
242 if (localPart == null) {
243 throw new IllegalArgumentException(
244 "local part cannot be \"null\" when creating a QName");
245 }
246 this.localPart = localPart;
247
248 // prefix is required
249 if (prefix == null) {
250 throw new IllegalArgumentException(
251 "prefix cannot be \"null\" when creating a QName");
252 }
253 this.prefix = prefix;
254 }
255
256 /**
257 * <p><code>QName</code> constructor specifying the local part.</p>
258 *
259 * <p>If the local part is <code>null</code> an
260 * <code>IllegalArgumentException</code> is thrown.
261 * A local part of "" is allowed to preserve
262 * compatible behavior with QName 1.0. </p>
263 *
264 * <p>When using this constructor, the Namespace URI is set to
265 * {@link javax.xml.XMLConstants#NULL_NS_URI
266 * XMLConstants.NULL_NS_URI} and the prefix is set to {@link
267 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
268 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
269 *
270 * <p><em>In an XML context, all Element and Attribute names exist
271 * in the context of a Namespace. Making this explicit during the
272 * construction of a <code>QName</code> helps prevent hard to
273 * diagnosis XML validity errors. The constructors {@link
274 * #QName(String namespaceURI, String localPart) QName(String
275 * namespaceURI, String localPart)} and
276 * {@link #QName(String namespaceURI, String localPart, String prefix)}
277 * are preferred.</em></p>
278 *
279 * <p>The local part is not validated as a
280 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
281 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
282 * in XML</a>.</p>
283 *
284 * @param localPart local part of the <code>QName</code>
285 *
286 * @throws IllegalArgumentException When <code>localPart</code> is
287 * <code>null</code>
288 *
289 * @see #QName(String namespaceURI, String localPart) QName(String
290 * namespaceURI, String localPart)
291 * @see #QName(String namespaceURI, String localPart, String
292 * prefix) QName(String namespaceURI, String localPart, String
293 * prefix)
294 */
295 public QName(String localPart) {
296 this(
297 XMLConstants.NULL_NS_URI,
298 localPart,
299 XMLConstants.DEFAULT_NS_PREFIX);
300 }
301
302 /**
303 * <p>Get the Namespace URI of this <code>QName</code>.</p>
304 *
305 * @return Namespace URI of this <code>QName</code>
306 */
307 public String getNamespaceURI() {
308 return namespaceURI;
309 }
310
311 /**
312 * <p>Get the local part of this <code>QName</code>.</p>
313 *
314 * @return local part of this <code>QName</code>
315 */
316 public String getLocalPart() {
317 return localPart;
318 }
319
320 /**
321 * <p>Get the prefix of this <code>QName</code>.</p>
322 *
323 * <p>The prefix assigned to a <code>QName</code> might
324 * <strong><em>NOT</em></strong> be valid in a different
325 * context. For example, a <code>QName</code> may be assigned a
326 * prefix in the context of parsing a document but that prefix may
327 * be invalid in the context of a different document.</p>
328 *
329 * @return prefix of this <code>QName</code>
330 */
331 public String getPrefix() {
332 return prefix;
333 }
334
335 /**
336 * <p>Test this <code>QName</code> for equality with another
337 * <code>Object</code>.</p>
338 *
339 * <p>If the <code>Object</code> to be tested is not a
340 * <code>QName</code> or is <code>null</code>, then this method
341 * returns <code>false</code>.</p>
342 *
343 * <p>Two <code>QName</code>s are considered equal if and only if
344 * both the Namespace URI and local part are equal. This method
345 * uses <code>String.equals()</code> to check equality of the
346 * Namespace URI and local part. The prefix is
347 * <strong><em>NOT</em></strong> used to determine equality.</p>
348 *
349 * <p>This method satisfies the general contract of {@link
350 * java.lang.Object#equals(Object) Object.equals(Object)}</p>
351 *
352 * @param objectToTest the <code>Object</code> to test for
353 * equality with this <code>QName</code>
354 * @return <code>true</code> if the given <code>Object</code> is
355 * equal to this <code>QName</code> else <code>false</code>
356 */
357 public final boolean equals(Object objectToTest) {
358 if (objectToTest == this) {
359 return true;
360 }
361
362 if (objectToTest == null || !(objectToTest instanceof QName)) {
363 return false;
364 }
365
366 QName qName = (QName) objectToTest;
367
368 return localPart.equals(qName.localPart)
369 && namespaceURI.equals(qName.namespaceURI);
370 }
371
372 /**
373 * <p>Generate the hash code for this <code>QName</code>.</p>
374 *
375 * <p>The hash code is calculated using both the Namespace URI and
376 * the local part of the <code>QName</code>. The prefix is
377 * <strong><em>NOT</em></strong> used to calculate the hash
378 * code.</p>
379 *
380 * <p>This method satisfies the general contract of {@link
381 * java.lang.Object#hashCode() Object.hashCode()}.</p>
382 *
383 * @return hash code for this <code>QName</code> <code>Object</code>
384 */
385 public final int hashCode() {
386 return namespaceURI.hashCode() ^ localPart.hashCode();
387 }
388
389 /**
390 * <p><code>String</code> representation of this
391 * <code>QName</code>.</p>
392 *
393 * <p>The commonly accepted way of representing a <code>QName</code>
394 * as a <code>String</code> was
395 * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
396 * by James Clark. Although this is not a <em>standard</em>
397 * specification, it is in common use, e.g. {@link
398 * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
399 * This implementation represents a <code>QName</code> as:
400 * "{" + Namespace URI + "}" + local part. If the Namespace URI
401 * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
402 * local part is returned. An appropriate use of this method is
403 * for debugging or logging for human consumption.</p>
404 *
405 * <p>Note the prefix value is <strong><em>NOT</em></strong>
406 * returned as part of the <code>String</code> representation.</p>
407 *
408 * <p>This method satisfies the general contract of {@link
409 * java.lang.Object#toString() Object.toString()}.</p>
410 *
411 * @return <code>String</code> representation of this <code>QName</code>
412 */
413 public String toString() {
414 if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
415 return localPart;
416 } else {
417 return "{" + namespaceURI + "}" + localPart;
418 }
419 }
420
421 /**
422 * <p><code>QName</code> derived from parsing the formatted
423 * <code>String</code>.</p>
424 *
425 * <p>If the <code>String</code> is <code>null</code> or does not conform to
426 * {@link #toString() QName.toString()} formatting, an
427 * <code>IllegalArgumentException</code> is thrown.</p>
428 *
429 * <p><em>The <code>String</code> <strong>MUST</strong> be in the
430 * form returned by {@link #toString() QName.toString()}.</em></p>
431 *
432 * <p>The commonly accepted way of representing a <code>QName</code>
433 * as a <code>String</code> was
434 * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
435 * by James Clark. Although this is not a <em>standard</em>
436 * specification, it is in common use, e.g. {@link
437 * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
438 * This implementation parses a <code>String</code> formatted
439 * as: "{" + Namespace URI + "}" + local part. If the Namespace
440 * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
441 * local part should be provided.</p>
442 *
443 * <p>The prefix value <strong><em>CANNOT</em></strong> be
444 * represented in the <code>String</code> and will be set to
445 * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
446 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
447 *
448 * <p>This method does not do full validation of the resulting
449 * <code>QName</code>.
450 * <p>The Namespace URI is not validated as a
451 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
452 * The local part is not validated as a
453 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
454 * as specified in
455 * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
456 *
457 * @param qNameAsString <code>String</code> representation
458 * of the <code>QName</code>
459 *
460 * @throws IllegalArgumentException When <code>qNameAsString</code> is
461 * <code>null</code> or malformed
462 *
463 * @return <code>QName</code> corresponding to the given <code>String</code>
464 * @see #toString() QName.toString()
465 */
466 public static QName valueOf(String qNameAsString) {
467
468 // null is not valid
469 if (qNameAsString == null) {
470 throw new IllegalArgumentException(
471 "cannot create QName from \"null\" or \"\" String");
472 }
473
474 // "" local part is valid to preserve compatible behavior with QName 1.0
475 if (qNameAsString.length() == 0) {
476 return new QName(
477 XMLConstants.NULL_NS_URI,
478 qNameAsString,
479 XMLConstants.DEFAULT_NS_PREFIX);
480 }
481
482 // local part only?
483 if (qNameAsString.charAt(0) != '{') {
484 return new QName(
485 XMLConstants.NULL_NS_URI,
486 qNameAsString,
487 XMLConstants.DEFAULT_NS_PREFIX);
488 }
489
490 // Namespace URI improperly specified?
491 if (qNameAsString.startsWith("{" + XMLConstants.NULL_NS_URI + "}")) {
492 throw new IllegalArgumentException(
493 "Namespace URI .equals(XMLConstants.NULL_NS_URI), "
494 + ".equals(\"" + XMLConstants.NULL_NS_URI + "\"), "
495 + "only the local part, "
496 + "\""
497 + qNameAsString.substring(2 + XMLConstants.NULL_NS_URI.length())
498 + "\", "
499 + "should be provided.");
500 }
501
502 // Namespace URI and local part specified
503 int endOfNamespaceURI = qNameAsString.indexOf('}');
504 if (endOfNamespaceURI == -1) {
505 throw new IllegalArgumentException(
506 "cannot create QName from \""
507 + qNameAsString
508 + "\", missing closing \"}\"");
509 }
510 return new QName(
511 qNameAsString.substring(1, endOfNamespaceURI),
512 qNameAsString.substring(endOfNamespaceURI + 1),
513 XMLConstants.DEFAULT_NS_PREFIX);
514 }
515 }