001 /*
002 * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.namespace;
027
028 import java.io.Serializable;
029 import java.security.AccessController;
030 import java.security.PrivilegedAction;
031
032 import javax.xml.XMLConstants;
033
034 /**
035 * <p><code>QName</code> represents a <strong>qualified name</strong>
036 * as defined in the XML specifications: <a
037 * href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
038 * Datatypes specification</a>, <a
039 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
040 * in XML</a>, <a
041 * href="http://www.w3.org/XML/xml-names-19990114-errata">Namespaces
042 * in XML Errata</a>.</p>
043 *
044 * <p>The value of a <code>QName</code> contains a <strong>Namespace
045 * URI</strong>, <strong>local part</strong> and
046 * <strong>prefix</strong>.</p>
047 *
048 * <p>The prefix is included in <code>QName</code> to retain lexical
049 * information <strong><em>when present</em></strong> in an {@link
050 * javax.xml.transform.Source XML input source}. The prefix is
051 * <strong><em>NOT</em></strong> used in {@link #equals(Object)
052 * QName.equals(Object)} or to compute the {@link #hashCode()
053 * QName.hashCode()}. Equality and the hash code are defined using
054 * <strong><em>only</em></strong> the Namespace URI and local part.</p>
055 *
056 * <p>If not specified, the Namespace URI is set to {@link
057 * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
058 * If not specified, the prefix is set to {@link
059 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
060 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
061 *
062 * <p><code>QName</code> is immutable.</p>
063 *
064 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
065 * @version $Revision: 1.5 $, $Date: 2005/11/03 19:34:20 $
066 * @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
067 * XML Schema Part2: Datatypes specification</a>
068 * @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
069 * Namespaces in XML</a>
070 * @see <a href="http://www.w3.org/XML/xml-names-19990114-errata">
071 * Namespaces in XML Errata</a>
072 * @since 1.5
073 */
074
075 public class QName implements Serializable {
076
077 /**
078 * <p>Stream Unique Identifier.</p>
079 *
080 * <p>Due to a historical defect, QName was released with multiple
081 * serialVersionUID values even though its serialization was the
082 * same.</p>
083 *
084 * <p>To workaround this issue, serialVersionUID is set with either
085 * a default value or a compatibility value. To use the
086 * compatiblity value, set the system property:</p>
087 *
088 * <code>com.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0</code>
089 *
090 * <p>This workaround was inspired by classes in the javax.management
091 * package, e.g. ObjectName, etc.
092 * See CR6267224 for original defect report.</p>
093 */
094 private static final long serialVersionUID;
095 /**
096 * <p>Default <code>serialVersionUID</code> value.</p>
097 */
098 private static final long defaultSerialVersionUID = -9120448754896609940L;
099 /**
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
111 .doPrivileged(new PrivilegedAction() {
112 public Object run() {
113 return System
114 .getProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID");
115 }
116 });
117 useDefaultSerialVersionUID = (valueUseCompatibleSerialVersionUID != null && valueUseCompatibleSerialVersionUID
118 .equals("1.0")) ? false : true;
119 } catch (Exception exception) {
120 // use default if any Exceptions
121 useDefaultSerialVersionUID = true;
122 }
123
124 // set serialVersionUID to desired value
125 if (useDefaultSerialVersionUID) {
126 serialVersionUID = defaultSerialVersionUID;
127 } else {
128 serialVersionUID = compatibleSerialVersionUID;
129 }
130 }
131
132 /**
133 * <p>Namespace URI of this <code>QName</code>.</p>
134 */
135 private final String namespaceURI;
136
137 /**
138 * <p>local part of this <code>QName</code>.</p>
139 */
140 private final String localPart;
141
142 /**
143 * <p>prefix of this <code>QName</code>.</p>
144 */
145 private final String prefix;
146
147 /**
148 * <p><code>QName</code> constructor specifying the Namespace URI
149 * and local part.</p>
150 *
151 * <p>If the Namespace URI is <code>null</code>, it is set to
152 * {@link javax.xml.XMLConstants#NULL_NS_URI
153 * XMLConstants.NULL_NS_URI}. This value represents no
154 * explicitly defined Namespace as defined by the <a
155 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
156 * in XML</a> specification. This action preserves compatible
157 * behavior with QName 1.0. Explicitly providing the {@link
158 * javax.xml.XMLConstants#NULL_NS_URI
159 * XMLConstants.NULL_NS_URI} value is the preferred coding
160 * style.</p>
161 *
162 * <p>If the local part is <code>null</code> an
163 * <code>IllegalArgumentException</code> is thrown.
164 * A local part of "" is allowed to preserve
165 * compatible behavior with QName 1.0. </p>
166 *
167 * <p>When using this constructor, the prefix is set to {@link
168 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
169 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
170 *
171 * <p>The Namespace URI is not validated as a
172 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
173 * The local part is not validated as a
174 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
175 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
176 * in XML</a>.</p>
177 *
178 * @param namespaceURI Namespace URI of the <code>QName</code>
179 * @param localPart local part of the <code>QName</code>
180 *
181 * @throws IllegalArgumentException When <code>localPart</code> is
182 * <code>null</code>
183 *
184 * @see #QName(String namespaceURI, String localPart, String
185 * prefix) QName(String namespaceURI, String localPart, String
186 * prefix)
187 */
188 public QName(final String namespaceURI, final String localPart) {
189 this (namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX);
190 }
191
192 /**
193 * <p><code>QName</code> constructor specifying the Namespace URI,
194 * local part and prefix.</p>
195 *
196 * <p>If the Namespace URI is <code>null</code>, it is set to
197 * {@link javax.xml.XMLConstants#NULL_NS_URI
198 * XMLConstants.NULL_NS_URI}. This value represents no
199 * explicitly defined Namespace as defined by the <a
200 * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
201 * in XML</a> specification. This action preserves compatible
202 * behavior with QName 1.0. Explicitly providing the {@link
203 * javax.xml.XMLConstants#NULL_NS_URI
204 * XMLConstants.NULL_NS_URI} value is the preferred coding
205 * style.</p>
206 *
207 * <p>If the local part is <code>null</code> an
208 * <code>IllegalArgumentException</code> is thrown.
209 * A local part of "" is allowed to preserve
210 * compatible behavior with QName 1.0. </p>
211 *
212 * <p>If the prefix is <code>null</code>, an
213 * <code>IllegalArgumentException</code> is thrown. Use {@link
214 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
215 * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no
216 * prefix is present or the prefix is not relevant.</p>
217 *
218 * <p>The Namespace URI is not validated as a
219 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
220 * The local part and prefix are not validated as a
221 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
222 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
223 * in XML</a>.</p>
224 *
225 * @param namespaceURI Namespace URI of the <code>QName</code>
226 * @param localPart local part of the <code>QName</code>
227 * @param prefix prefix of the <code>QName</code>
228 *
229 * @throws IllegalArgumentException When <code>localPart</code>
230 * or <code>prefix</code> is <code>null</code>
231 */
232 public QName(String namespaceURI, String localPart, String prefix) {
233
234 // map null Namespace URI to default
235 // to preserve compatibility with QName 1.0
236 if (namespaceURI == null) {
237 this .namespaceURI = XMLConstants.NULL_NS_URI;
238 } else {
239 this .namespaceURI = namespaceURI;
240 }
241
242 // local part is required.
243 // "" is allowed to preserve compatibility with QName 1.0
244 if (localPart == null) {
245 throw new IllegalArgumentException(
246 "local part cannot be \"null\" when creating a QName");
247 }
248 this .localPart = localPart;
249
250 // prefix is required
251 if (prefix == null) {
252 throw new IllegalArgumentException(
253 "prefix cannot be \"null\" when creating a QName");
254 }
255 this .prefix = prefix;
256 }
257
258 /**
259 * <p><code>QName</code> constructor specifying the local part.</p>
260 *
261 * <p>If the local part is <code>null</code> an
262 * <code>IllegalArgumentException</code> is thrown.
263 * A local part of "" is allowed to preserve
264 * compatible behavior with QName 1.0. </p>
265 *
266 * <p>When using this constructor, the Namespace URI is set to
267 * {@link javax.xml.XMLConstants#NULL_NS_URI
268 * XMLConstants.NULL_NS_URI} and the prefix is set to {@link
269 * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
270 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
271 *
272 * <p><em>In an XML context, all Element and Attribute names exist
273 * in the context of a Namespace. Making this explicit during the
274 * construction of a <code>QName</code> helps prevent hard to
275 * diagnosis XML validity errors. The constructors {@link
276 * #QName(String namespaceURI, String localPart) QName(String
277 * namespaceURI, String localPart)} and
278 * {@link #QName(String namespaceURI, String localPart, String prefix)}
279 * are preferred.</em></p>
280 *
281 * <p>The local part is not validated as a
282 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
283 * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
284 * in XML</a>.</p>
285 *
286 * @param localPart local part of the <code>QName</code>
287 *
288 * @throws IllegalArgumentException When <code>localPart</code> is
289 * <code>null</code>
290 *
291 * @see #QName(String namespaceURI, String localPart) QName(String
292 * namespaceURI, String localPart)
293 * @see #QName(String namespaceURI, String localPart, String
294 * prefix) QName(String namespaceURI, String localPart, String
295 * prefix)
296 */
297 public QName(String localPart) {
298 this (XMLConstants.NULL_NS_URI, 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 == null || !(objectToTest instanceof QName)) {
359 return false;
360 }
361
362 QName qName = (QName) objectToTest;
363
364 return namespaceURI.equals(qName.namespaceURI)
365 && localPart.equals(qName.localPart);
366 }
367
368 /**
369 * <p>Generate the hash code for this <code>QName</code>.</p>
370 *
371 * <p>The hash code is calculated using both the Namespace URI and
372 * the local part of the <code>QName</code>. The prefix is
373 * <strong><em>NOT</em></strong> used to calculate the hash
374 * code.</p>
375 *
376 * <p>This method satisfies the general contract of {@link
377 * java.lang.Object#hashCode() Object.hashCode()}.</p>
378 *
379 * @return hash code for this <code>QName</code> <code>Object</code>
380 */
381 public final int hashCode() {
382 return namespaceURI.hashCode() ^ localPart.hashCode();
383 }
384
385 /**
386 * <p><code>String</code> representation of this
387 * <code>QName</code>.</p>
388 *
389 * <p>The commonly accepted way of representing a <code>QName</code>
390 * as a <code>String</code> was
391 * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
392 * by James Clark. Although this is not a <em>standard</em>
393 * specification, it is in common use, e.g. {@link
394 * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
395 * This implementation represents a <code>QName</code> as:
396 * "{" + Namespace URI + "}" + local part. If the Namespace URI
397 * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
398 * local part is returned. An appropriate use of this method is
399 * for debugging or logging for human consumption.</p>
400 *
401 * <p>Note the prefix value is <strong><em>NOT</em></strong>
402 * returned as part of the <code>String</code> representation.</p>
403 *
404 * <p>This method satisfies the general contract of {@link
405 * java.lang.Object#toString() Object.toString()}.</p>
406 *
407 * @return <code>String</code> representation of this <code>QName</code>
408 */
409 public String toString() {
410 if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
411 return localPart;
412 } else {
413 return "{" + namespaceURI + "}" + localPart;
414 }
415 }
416
417 /**
418 * <p><code>QName</code> derived from parsing the formatted
419 * <code>String</code>.</p>
420 *
421 * <p>If the <code>String</code> is <code>null</code> or does not conform to
422 * {@link #toString() QName.toString()} formatting, an
423 * <code>IllegalArgumentException</code> is thrown.</p>
424 *
425 * <p><em>The <code>String</code> <strong>MUST</strong> be in the
426 * form returned by {@link #toString() QName.toString()}.</em></p>
427 *
428 * <p>The commonly accepted way of representing a <code>QName</code>
429 * as a <code>String</code> was
430 * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
431 * by James Clark. Although this is not a <em>standard</em>
432 * specification, it is in common use, e.g. {@link
433 * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
434 * This implementation parses a <code>String</code> formatted
435 * as: "{" + Namespace URI + "}" + local part. If the Namespace
436 * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
437 * local part should be provided.</p>
438 *
439 * <p>The prefix value <strong><em>CANNOT</em></strong> be
440 * represented in the <code>String</code> and will be set to
441 * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
442 * XMLConstants.DEFAULT_NS_PREFIX}.</p>
443 *
444 * <p>This method does not do full validation of the resulting
445 * <code>QName</code>.
446 * <p>The Namespace URI is not validated as a
447 * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
448 * The local part is not validated as a
449 * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
450 * as specified in
451 * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
452 *
453 * @param qNameAsString <code>String</code> representation
454 * of the <code>QName</code>
455 *
456 * @throws IllegalArgumentException When <code>qNameAsString</code> is
457 * <code>null</code> or malformed
458 *
459 * @return <code>QName</code> corresponding to the given <code>String</code>
460 * @see #toString() QName.toString()
461 */
462 public static QName valueOf(String qNameAsString) {
463
464 // null is not valid
465 if (qNameAsString == null) {
466 throw new IllegalArgumentException(
467 "cannot create QName from \"null\" or \"\" String");
468 }
469
470 // "" local part is valid to preserve compatible behavior with QName 1.0
471 if (qNameAsString.length() == 0) {
472 return new QName(XMLConstants.NULL_NS_URI, qNameAsString,
473 XMLConstants.DEFAULT_NS_PREFIX);
474 }
475
476 // local part only?
477 if (qNameAsString.charAt(0) != '{') {
478 return new QName(XMLConstants.NULL_NS_URI, qNameAsString,
479 XMLConstants.DEFAULT_NS_PREFIX);
480 }
481
482 // Namespace URI improperly specified?
483 if (qNameAsString.startsWith("{" + XMLConstants.NULL_NS_URI
484 + "}")) {
485 throw new IllegalArgumentException(
486 "Namespace URI .equals(XMLConstants.NULL_NS_URI), "
487 + ".equals(\""
488 + XMLConstants.NULL_NS_URI
489 + "\"), "
490 + "only the local part, "
491 + "\""
492 + qNameAsString
493 .substring(2 + XMLConstants.NULL_NS_URI
494 .length()) + "\", "
495 + "should be provided.");
496 }
497
498 // Namespace URI and local part specified
499 int endOfNamespaceURI = qNameAsString.indexOf('}');
500 if (endOfNamespaceURI == -1) {
501 throw new IllegalArgumentException(
502 "cannot create QName from \"" + qNameAsString
503 + "\", missing closing \"}\"");
504 }
505 return new QName(qNameAsString.substring(1, endOfNamespaceURI),
506 qNameAsString.substring(endOfNamespaceURI + 1),
507 XMLConstants.DEFAULT_NS_PREFIX);
508 }
509 }
|