FileDocCategorySizeDatePackage
QName.javaAPI DocJava SE 6 API20279Tue Jun 10 00:27:08 BST 2008javax.xml.namespace

QName

public class QName extends Object implements Serializable

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.5 $, $Date: 2005/11/03 19:34:20 $
see
XML Schema Part2: Datatypes specification
see
Namespaces in XML
see
Namespaces in XML Errata
since
1.5

Fields Summary
private static final long
serialVersionUID

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
defaultSerialVersionUID

Default serialVersionUID value.

private static final long
compatibleSerialVersionUID

Compatibility serialVersionUID value.

private static boolean
useDefaultSerialVersionUID

Flag to use default or campatible serialVersionUID.

private final String
namespaceURI

Namespace URI of this QName.

private final String
localPart

local part of this QName.

private final String
prefix

prefix of this QName.

Constructors Summary
public QName(String namespaceURI, String localPart)

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)

        this(namespaceURI, localPart, XMLConstants.DEFAULT_NS_PREFIX);
    
public QName(String namespaceURI, String localPart, String 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


        // 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;
    
public QName(String localPart)

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)

        this(
            XMLConstants.NULL_NS_URI,
            localPart,
            XMLConstants.DEFAULT_NS_PREFIX);
    
Methods Summary
public final booleanequals(java.lang.Object objectToTest)

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

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

        QName qName = (QName) objectToTest;

        return namespaceURI.equals(qName.namespaceURI)
            && localPart.equals(qName.localPart);
    
public java.lang.StringgetLocalPart()

Get the local part of this QName.

return
local part of this QName

        return localPart;
    
public java.lang.StringgetNamespaceURI()

Get the Namespace URI of this QName.

return
Namespace URI of this QName

        return namespaceURI;
    
public java.lang.StringgetPrefix()

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

        return prefix;
    
public final inthashCode()

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

        return namespaceURI.hashCode() ^ localPart.hashCode();
    
public java.lang.StringtoString()

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

        if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
            return localPart;
        } else {
            return "{" + namespaceURI + "}" + localPart;
        }
    
public static javax.xml.namespace.QNamevalueOf(java.lang.String 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
throws
IllegalArgumentException When qNameAsString is null or malformed
return
QName corresponding to the given String
see
#toString() QName.toString()


        // 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);