Back to index...

	/*
	* Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.xml.namespace;

	import java.io.Serializable;
	import javax.xml.XMLConstants;
	import jdk.xml.internal.SecuritySupport;

	/**
	* <p><code>QName</code> represents a <strong>qualified name</strong>
	* as defined in the XML specifications: <a
	* href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part2:
	* Datatypes specification</a>, <a
	* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
	* in XML</a>.
	*
	* <p>The value of a <code>QName</code> contains a <strong>Namespace
	* URI</strong>, <strong>local part</strong> and
	* <strong>prefix</strong>.</p>
	*
	* <p>The prefix is included in <code>QName</code> to retain lexical
	* information <strong><em>when present</em></strong> in an {@link
	* javax.xml.transform.Source XML input source}. The prefix is
	* <strong><em>NOT</em></strong> used in {@link #equals(Object)
	* QName.equals(Object)} or to compute the {@link #hashCode()
	* QName.hashCode()}. Equality and the hash code are defined using
	* <strong><em>only</em></strong> the Namespace URI and local part.</p>
	*
	* <p>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}.</p>
	*
	* <p><code>QName</code> is immutable.</p>
	*
	* @author Jeff Suttor
	* @see <a href="http://www.w3.org/TR/xmlschema-2/#QName">
	* XML Schema Part2: Datatypes specification</a>
	* @see <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">
	* Namespaces in XML</a>
	* @since 1.5
	*/

	public class QName implements Serializable {
	// tests show that the ID is the same from JDK 1.5 through JDK 9
	private static final long serialVersionUID = -9120448754896609940L;

	/**
	* <p>Namespace URI of this <code>QName</code>.</p>
	*/
	private final String namespaceURI;

	/**
	* <p>local part of this <code>QName</code>.</p>
	*/
	private final String localPart;

	/**
	* <p>prefix of this <code>QName</code>.</p>
	*/
	private final String prefix;

	/**
	* <p><code>QName</code> constructor specifying the Namespace URI
	* and local part.</p>
	*
	* <p>If the Namespace URI is <code>null</code>, 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 <a
	* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
	* in XML</a> 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.</p>
	*
	* <p>If the local part is <code>null</code> an
	* <code>IllegalArgumentException</code> is thrown.
	* A local part of "" is allowed to preserve
	* compatible behavior with QName 1.0. </p>
	*
	* <p>When using this constructor, the prefix is set to {@link
	* javax.xml.XMLConstants#DEFAULT_NS_PREFIX
	* XMLConstants.DEFAULT_NS_PREFIX}.</p>
	*
	* <p>The Namespace URI is not validated as a
	* <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
	* The local part is not validated as a
	* <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
	* as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
	* in XML</a>.</p>
	*
	* @param namespaceURI Namespace URI of the <code>QName</code>
	* @param localPart local part of the <code>QName</code>
	*
	* @throws IllegalArgumentException When <code>localPart</code> is
	* <code>null</code>
	*
	* @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);
	}

	/**
	* <p><code>QName</code> constructor specifying the Namespace URI,
	* local part and prefix.</p>
	*
	* <p>If the Namespace URI is <code>null</code>, 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 <a
	* href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
	* in XML</a> 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.</p>
	*
	* <p>If the local part is <code>null</code> an
	* <code>IllegalArgumentException</code> is thrown.
	* A local part of "" is allowed to preserve
	* compatible behavior with QName 1.0. </p>
	*
	* <p>If the prefix is <code>null</code>, an
	* <code>IllegalArgumentException</code> 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.</p>
	*
	* <p>The Namespace URI is not validated as a
	* <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
	* The local part and prefix are not validated as a
	* <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
	* as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
	* in XML</a>.</p>
	*
	* @param namespaceURI Namespace URI of the <code>QName</code>
	* @param localPart local part of the <code>QName</code>
	* @param prefix prefix of the <code>QName</code>
	*
	* @throws IllegalArgumentException When <code>localPart</code>
	* or <code>prefix</code> is <code>null</code>
	*/
	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;
	}

	/**
	* <p><code>QName</code> constructor specifying the local part.</p>
	*
	* <p>If the local part is <code>null</code> an
	* <code>IllegalArgumentException</code> is thrown.
	* A local part of "" is allowed to preserve
	* compatible behavior with QName 1.0. </p>
	*
	* <p>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}.</p>
	*
	* <p><em>In an XML context, all Element and Attribute names exist
	* in the context of a Namespace. Making this explicit during the
	* construction of a <code>QName</code> 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.</em></p>
	*
	* <p>The local part is not validated as a
	* <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
	* as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
	* in XML</a>.</p>
	*
	* @param localPart local part of the <code>QName</code>
	*
	* @throws IllegalArgumentException When <code>localPart</code> is
	* <code>null</code>
	*
	* @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);
	}

	/**
	* <p>Get the Namespace URI of this <code>QName</code>.</p>
	*
	* @return Namespace URI of this <code>QName</code>
	*/
	public String getNamespaceURI() {
	return namespaceURI;
	}

	/**
	* <p>Get the local part of this <code>QName</code>.</p>
	*
	* @return local part of this <code>QName</code>
	*/
	public String getLocalPart() {
	return localPart;
	}

	/**
	* <p>Get the prefix of this <code>QName</code>.</p>
	*
	* <p>The prefix assigned to a <code>QName</code> might
	* <strong><em>NOT</em></strong> be valid in a different
	* context. For example, a <code>QName</code> 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.</p>
	*
	* @return prefix of this <code>QName</code>
	*/
	public String getPrefix() {
	return prefix;
	}

	/**
	* <p>Test this <code>QName</code> for equality with another
	* <code>Object</code>.</p>
	*
	* <p>If the <code>Object</code> to be tested is not a
	* <code>QName</code> or is <code>null</code>, then this method
	* returns <code>false</code>.</p>
	*
	* <p>Two <code>QName</code>s are considered equal if and only if
	* both the Namespace URI and local part are equal. This method
	* uses <code>String.equals()</code> to check equality of the
	* Namespace URI and local part. The prefix is
	* <strong><em>NOT</em></strong> used to determine equality.</p>
	*
	* <p>This method satisfies the general contract of {@link
	* java.lang.Object#equals(Object) Object.equals(Object)}</p>
	*
	* @param objectToTest the <code>Object</code> to test for
	* equality with this <code>QName</code>
	* @return <code>true</code> if the given <code>Object</code> is
	* equal to this <code>QName</code> else <code>false</code>
	*/
	public final boolean equals(Object objectToTest) {
	if (objectToTest == this) {
	return true;
	}

	if (objectToTest == null \|\| !(objectToTest instanceof QName)) {
	return false;
	}

	QName qName = (QName) objectToTest;

	return localPart.equals(qName.localPart)
	&& namespaceURI.equals(qName.namespaceURI);
	}

	/**
	* <p>Generate the hash code for this <code>QName</code>.</p>
	*
	* <p>The hash code is calculated using both the Namespace URI and
	* the local part of the <code>QName</code>. The prefix is
	* <strong><em>NOT</em></strong> used to calculate the hash
	* code.</p>
	*
	* <p>This method satisfies the general contract of {@link
	* java.lang.Object#hashCode() Object.hashCode()}.</p>
	*
	* @return hash code for this <code>QName</code> <code>Object</code>
	*/
	public final int hashCode() {
	return namespaceURI.hashCode() ^ localPart.hashCode();
	}

	/**
	* <p><code>String</code> representation of this
	* <code>QName</code>.</p>
	*
	* <p>The commonly accepted way of representing a <code>QName</code>
	* as a <code>String</code> was
	* <a href="http://jclark.com/xml/xmlns.htm">defined</a>
	* by James Clark. Although this is not a <em>standard</em>
	* specification, it is in common use, e.g. {@link
	* javax.xml.transform.Transformer#setParameter(String name, Object value)}.
	* This implementation represents a <code>QName</code> as:
	* "{" + Namespace URI + "}" + local part. If the Namespace URI
	* <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
	* local part is returned. An appropriate use of this method is
	* for debugging or logging for human consumption.</p>
	*
	* <p>Note the prefix value is <strong><em>NOT</em></strong>
	* returned as part of the <code>String</code> representation.</p>
	*
	* <p>This method satisfies the general contract of {@link
	* java.lang.Object#toString() Object.toString()}.</p>
	*
	* @return <code>String</code> representation of this <code>QName</code>
	*/
	public String toString() {
	if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
	return localPart;
	} else {
	return "{" + namespaceURI + "}" + localPart;
	}
	}

	/**
	* <p><code>QName</code> derived from parsing the formatted
	* <code>String</code>.</p>
	*
	* <p>If the <code>String</code> is <code>null</code> or does not conform to
	* {@link #toString() QName.toString()} formatting, an
	* <code>IllegalArgumentException</code> is thrown.</p>
	*
	* <p><em>The <code>String</code> <strong>MUST</strong> be in the
	* form returned by {@link #toString() QName.toString()}.</em></p>
	*
	* <p>The commonly accepted way of representing a <code>QName</code>
	* as a <code>String</code> was
	* <a href="http://jclark.com/xml/xmlns.htm">defined</a>
	* by James Clark. Although this is not a <em>standard</em>
	* specification, it is in common use, e.g. {@link
	* javax.xml.transform.Transformer#setParameter(String name, Object value)}.
	* This implementation parses a <code>String</code> formatted
	* as: "{" + Namespace URI + "}" + local part. If the Namespace
	* URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
	* local part should be provided.</p>
	*
	* <p>The prefix value <strong><em>CANNOT</em></strong> be
	* represented in the <code>String</code> and will be set to
	* {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
	* XMLConstants.DEFAULT_NS_PREFIX}.</p>
	*
	* <p>This method does not do full validation of the resulting
	* <code>QName</code>.
	* <p>The Namespace URI is not validated as a
	* <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
	* The local part is not validated as a
	* <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
	* as specified in
	* <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
	*
	* @param qNameAsString <code>String</code> representation
	* of the <code>QName</code>
	*
	* @throws IllegalArgumentException When <code>qNameAsString</code> is
	* <code>null</code> or malformed
	*
	* @return <code>QName</code> corresponding to the given <code>String</code>
	* @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);
	}
	}

Back to index...