/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ // $Id: QName.java 754581 2009-03-15 01:32:39Z mrglavas $ package javax.xml.namespace; import java.io.IOException; import java.io.ObjectInputStream; import java.io.Serializable; import java.security.AccessController; import java.security.PrivilegedAction; import javax.xml.XMLConstants; /** *

QName represents a qualified name * as defined in the XML specifications: XML Schema Part2: * Datatypes specification, Namespaces * in XML, Namespaces * in XML Errata.

* *

The value of a QName contains a Namespace * URI, local part and * prefix.

* *

The prefix is included in QName to retain lexical * information when present in an {@link * javax.xml.transform.Source XML input source}. The prefix is * NOT used in {@link #equals(Object) * QName.equals(Object)} or to compute the {@link #hashCode() * QName.hashCode()}. Equality and the hash code are defined using * only the Namespace URI and local part.

* *

If not specified, the Namespace URI is set to {@link * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}. * If not specified, the prefix is set to {@link * javax.xml.XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX}.

* *

QName is immutable.

* * @author Jeff Suttor * @version $Revision: 754581 $, $Date: 2009-03-14 18:32:39 -0700 (Sat, 14 Mar 2009) $ * @see XML Schema Part2: Datatypes specification * @see Namespaces in XML * @see Namespaces in XML Errata * @since 1.5 */ public class QName implements Serializable { /** *

Stream Unique Identifier.

* *

To enable the compatibility serialVersionUID * set the System Property * org.apache.xml.namespace.QName.useCompatibleSerialVersionUID * to a value of "1.0".

*/ private static final long serialVersionUID; /** *

The original default Stream Unique Identifier.

*/ private static final long defaultSerialVersionUID = -9120448754896609940L; /** *

The compatibility Stream Unique Identifier that was introduced * with Java 5 SE SDK.

*/ private static final long compatibilitySerialVersionUID = 4418622981026545151L; static { String compatPropValue = System.getProperty("org.apache.xml.namespace.QName.useCompatibleSerialVersionUID"); // If 1.0 use compatibility serialVersionUID serialVersionUID = !"1.0".equals(compatPropValue) ? defaultSerialVersionUID : compatibilitySerialVersionUID; } /** *

Namespace URI of this QName.

*/ private final String namespaceURI; /** *

local part of this QName.

*/ private final String localPart; /** *

prefix of this QName.

*/ private String prefix; /** *

String representation of this QName.

*/ private transient String qNameAsString; /** *

QName constructor specifying the Namespace URI * and local part.

* *

If the Namespace URI is null, it is set to * {@link javax.xml.XMLConstants#NULL_NS_URI * XMLConstants.NULL_NS_URI}. This value represents no * explicitly defined Namespace as defined by the Namespaces * in XML specification. This action preserves compatible * behavior with QName 1.0. Explicitly providing the {@link * javax.xml.XMLConstants#NULL_NS_URI * XMLConstants.NULL_NS_URI} value is the preferred coding * style.

* *

If the local part is null an * IllegalArgumentException is thrown. * A local part of "" is allowed to preserve * compatible behavior with QName 1.0.

* *

When using this constructor, the prefix is set to {@link * javax.xml.XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX}.

* *

The Namespace URI is not validated as a * URI reference. * The local part is not validated as a * NCName * as specified in Namespaces * in XML.

* * @param namespaceURI Namespace URI of the QName * @param localPart local part of the QName * * @see #QName(String namespaceURI, String localPart, String * prefix) QName(String namespaceURI, String localPart, String * prefix) */ public QName(final String namespaceURI, final String localPart) { this(namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX); } /** *

QName constructor specifying the Namespace URI, * local part and prefix.

* *

If the local part is null an * IllegalArgumentException is thrown. * A local part of "" is allowed to preserve * compatible behavior with QName 1.0.

* *

If the prefix is null, an * IllegalArgumentException is thrown. Use {@link * javax.xml.XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no * prefix is present or the prefix is not relevant.

* *

The Namespace URI is not validated as a * URI reference. * The local part and prefix are not validated as a * NCName * as specified in Namespaces * in XML.

* * @param namespaceURI Namespace URI of the QName * @param localPart local part of the QName * @param prefix prefix of the QName */ public QName(String namespaceURI, String localPart, String prefix) { // map null Namespace URI to default to preserve compatibility with QName 1.0 if (namespaceURI == null) { this.namespaceURI = XMLConstants.NULL_NS_URI; } else { this.namespaceURI = namespaceURI; } // local part is required. "" is allowed to preserve compatibility with QName 1.0 if (localPart == null) { throw new IllegalArgumentException("local part cannot be \"null\" when creating a QName"); } this.localPart = localPart; // prefix is required if (prefix == null) { throw new IllegalArgumentException("prefix cannot be \"null\" when creating a QName"); } this.prefix = prefix; } /** *

QName constructor specifying the local part.

* *

If the local part is null an * IllegalArgumentException is thrown. * A local part of "" is allowed to preserve * compatible behavior with QName 1.0.

* *

When using this constructor, the Namespace URI is set to * {@link javax.xml.XMLConstants#NULL_NS_URI * XMLConstants.NULL_NS_URI} and the prefix is set to {@link * javax.xml.XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX}.

* *

In an XML context, all Element and Attribute names exist * in the context of a Namespace. Making this explicit during the * construction of a QName helps prevent hard to * diagnosis XML validity errors. The constructors {@link * #QName(String namespaceURI, String localPart) QName(String * namespaceURI, String localPart)} and * {@link #QName(String namespaceURI, String localPart, String prefix)} * are preferred.

* *

The local part is not validated as a * NCName * as specified in Namespaces * in XML.

* * @param localPart local part of the QName * @see #QName(String namespaceURI, String localPart) QName(String * namespaceURI, String localPart) * @see #QName(String namespaceURI, String localPart, String * prefix) QName(String namespaceURI, String localPart, String * prefix) */ public QName(String localPart) { this( XMLConstants.NULL_NS_URI, localPart, XMLConstants.DEFAULT_NS_PREFIX); } /** *

Get the Namespace URI of this QName.

* * @return Namespace URI of this QName */ public String getNamespaceURI() { return namespaceURI; } /** *

Get the local part of this QName.

* * @return local part of this QName */ public String getLocalPart() { return localPart; } /** *

Get the prefix of this QName.

* *

The prefix assigned to a QName might * NOT be valid in a different * context. For example, a QName may be assigned a * prefix in the context of parsing a document but that prefix may * be invalid in the context of a different document.

* * @return prefix of this QName */ public String getPrefix() { return prefix; } /** *

Test this QName for equality with another * Object.

* *

If the Object to be tested is not a * QName or is null, then this method * returns false.

* *

Two QNames are considered equal if and only if * both the Namespace URI and local part are equal. This method * uses String.equals() to check equality of the * Namespace URI and local part. The prefix is * NOT used to determine equality.

* *

This method satisfies the general contract of {@link * java.lang.Object#equals(Object) Object.equals(Object)}

* * @param objectToTest the Object to test for * equality with this QName * @return true if the given Object is * equal to this QName else false */ public final boolean equals(Object objectToTest) { // Is this the same object? if (objectToTest == this) { return true; } // Is this a QName? if (objectToTest instanceof QName) { QName qName = (QName) objectToTest; return localPart.equals(qName.localPart) && namespaceURI.equals(qName.namespaceURI); } return false; } /** *

Generate the hash code for this QName.

* *

The hash code is calculated using both the Namespace URI and * the local part of the QName. The prefix is * NOT used to calculate the hash * code.

* *

This method satisfies the general contract of {@link * java.lang.Object#hashCode() Object.hashCode()}.

* * @return hash code for this QName Object */ public final int hashCode() { return namespaceURI.hashCode() ^ localPart.hashCode(); } /** *

String representation of this * QName.

* *

The commonly accepted way of representing a QName * as a String was defined * by James Clark. Although this is not a standard * specification, it is in common use, e.g. {@link javax.xml.transform.Transformer#setParameter(String name, Object value)}. * This implementation represents a QName as: * "{" + Namespace URI + "}" + local part. If the Namespace URI * .equals(XMLConstants.NULL_NS_URI), only the * local part is returned. An appropriate use of this method is * for debugging or logging for human consumption.

* *

Note the prefix value is NOT * returned as part of the String representation.

* *

This method satisfies the general contract of {@link * java.lang.Object#toString() Object.toString()}.

* * @return String representation of this QName */ public String toString() { String _qNameAsString = qNameAsString; if (_qNameAsString == null) { final int nsLength = namespaceURI.length(); if (nsLength == 0) { _qNameAsString = localPart; } else { StringBuilder buffer = new StringBuilder(nsLength + localPart.length() + 2); buffer.append('{'); buffer.append(namespaceURI); buffer.append('}'); buffer.append(localPart); _qNameAsString = buffer.toString(); } qNameAsString = _qNameAsString; } return _qNameAsString; } /** *

QName derived from parsing the formatted * String.

* *

If the String is null or does not conform to * {@link #toString() QName.toString()} formatting, an * IllegalArgumentException is thrown.

* *

The String MUST be in the * form returned by {@link #toString() QName.toString()}.

* *

The commonly accepted way of representing a QName * as a String was defined * by James Clark. Although this is not a standard * specification, it is in common use, e.g. {@link javax.xml.transform.Transformer#setParameter(String name, Object value)}. * This implementation parses a String formatted * as: "{" + Namespace URI + "}" + local part. If the Namespace * URI .equals(XMLConstants.NULL_NS_URI), only the * local part should be provided.

* *

The prefix value CANNOT be * represented in the String and will be set to * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX}.

* *

This method does not do full validation of the resulting * QName. *

The Namespace URI is not validated as a * URI reference. * The local part is not validated as a * NCName * as specified in * Namespaces in XML.

* * @param qNameAsString String representation * of the QName * @return QName corresponding to the given String * @see #toString() QName.toString() */ public static QName valueOf(String qNameAsString) { // null is not valid if (qNameAsString == null) { throw new IllegalArgumentException("cannot create QName from \"null\" or \"\" String"); } // "" local part is valid to preserve compatible behavior with QName 1.0 if (qNameAsString.length() == 0) { return new QName( XMLConstants.NULL_NS_URI, qNameAsString, XMLConstants.DEFAULT_NS_PREFIX); } // local part only? if (qNameAsString.charAt(0) != '{') { return new QName( XMLConstants.NULL_NS_URI, qNameAsString, XMLConstants.DEFAULT_NS_PREFIX); } // Namespace URI improperly specified? if (qNameAsString.startsWith("{" + XMLConstants.NULL_NS_URI + "}")) { throw new IllegalArgumentException( "Namespace URI .equals(XMLConstants.NULL_NS_URI), " + ".equals(\"" + XMLConstants.NULL_NS_URI + "\"), " + "only the local part, " + "\"" + qNameAsString.substring(2 + XMLConstants.NULL_NS_URI.length()) + "\", " + "should be provided."); } // Namespace URI and local part specified int endOfNamespaceURI = qNameAsString.indexOf('}'); if (endOfNamespaceURI == -1) { throw new IllegalArgumentException( "cannot create QName from \"" + qNameAsString + "\", missing closing \"}\""); } return new QName( qNameAsString.substring(1, endOfNamespaceURI), qNameAsString.substring(endOfNamespaceURI + 1), XMLConstants.DEFAULT_NS_PREFIX); } /* * For old versions of QName which didn't have a prefix field, * ObjectInputStream.defaultReadObject() will initialize * the prefix to null instead of the empty string. This * method fixes up the prefix field if it didn't exist in the serialized * object. */ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); if (prefix == null) { prefix = XMLConstants.DEFAULT_NS_PREFIX; } } }