javax.xml.namespace.QName Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* https://jaxp.dev.java.net/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* HEADER in each file and include the License file at
* https://jaxp.dev.java.net/CDDLv1.0.html
* If applicable add the following below this CDDL HEADER
* with the fields enclosed by brackets "[]" replaced with
* your own identifying information: Portions Copyright
* [year] [name of copyright owner]
*/
/*
* $Id: QName.java,v 1.6 2006/04/06 00:26:39 jeffsuttor Exp $
* %W% %E%
*
* Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
*/
package javax.xml.namespace;
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: 1.6 $, $Date: 2006/04/06 00:26:39 $
* @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.
*
* Due to a historical defect, QName was released with multiple
* serialVersionUID values even though its serialization was the
* same.
*
* To workaround this issue, serialVersionUID is set with either
* a default value or a compatibility value. To use the
* compatiblity value, set the system property:
*
* com.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0
*
* This workaround was inspired by classes in the javax.management
* package, e.g. ObjectName, etc.
* See CR6267224 for original defect report.
*/
private static final long serialVersionUID;
/**
* Default serialVersionUID
value.
*/
private static final long defaultSerialVersionUID = -9120448754896609940L;
/**
* Compatibility serialVersionUID
value.
*/
private static final long compatibleSerialVersionUID = 4418622981026545151L;
/**
* Flag to use default or campatible serialVersionUID.
*/
private static boolean useDefaultSerialVersionUID = true;
static {
try {
// use a privileged block as reading a system property
String valueUseCompatibleSerialVersionUID = (String) AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
return System.getProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID");
}
}
);
useDefaultSerialVersionUID = (valueUseCompatibleSerialVersionUID != null && valueUseCompatibleSerialVersionUID.equals("1.0")) ? false : true;
} catch (Exception exception) {
// use default if any Exceptions
useDefaultSerialVersionUID = true;
}
// set serialVersionUID to desired value
if (useDefaultSerialVersionUID) {
serialVersionUID = defaultSerialVersionUID;
} else {
serialVersionUID = compatibleSerialVersionUID;
}
}
/**
* Namespace URI of this QName
.
*/
private final String namespaceURI;
/**
* local part of this QName
.
*/
private final String localPart;
/**
* prefix of this QName
.
*/
private final String prefix;
/**
* 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
*
* @throws IllegalArgumentException When localPart
is
* null
*
* @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 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.
*
* 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
*
* @throws IllegalArgumentException When localPart
* or prefix
is null
*/
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
*
* @throws IllegalArgumentException When localPart
is
* null
*
* @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 QName
s 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) {
if (objectToTest == null || !(objectToTest instanceof QName)) {
return false;
}
QName qName = (QName) objectToTest;
return namespaceURI.equals(qName.namespaceURI)
&& localPart.equals(qName.localPart);
}
/**
* 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() {
if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
return localPart;
} else {
return "{" + namespaceURI + "}" + localPart;
}
}
/**
* 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
*
* @throws IllegalArgumentException When qNameAsString
is
* null
or malformed
*
* @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);
}
}