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