QName (XML Standard API)
Date: 2018-10-17

javax.xml.namespace

## Class QName

- java.lang.Object
- - javax.xml.namespace.QName

- All Implemented Interfaces:
    java.io.Serializable

      public class QName
      extends java.lang.Object
      implements java.io.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 `XML input source`. The prefix is NOT used in `QName.equals(Object)` or to compute the `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 `XMLConstants.NULL_NS_URI`. If not specified, the prefix is set to `XMLConstants.DEFAULT_NS_PREFIX`.

  `QName` is immutable.

  Since:
    1.5
  Version:
    $Revision: 754581 $, $Date: 2009-03-14 21:32:39 -0400 (Sat, 14 Mar 2009) $
  Author:
    Jeff Suttor
  See Also:
    XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `QName(java.lang.String localPart)` `QName` constructor specifying the local part.
    `QName(java.lang.String namespaceURI, java.lang.String localPart)` `QName` constructor specifying the Namespace URI and local part.
    `QName(java.lang.String namespaceURI, java.lang.String localPart, java.lang.String prefix)` `QName` constructor specifying the Namespace URI, local part and prefix.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object objectToTest)` Test this `QName` for equality with another `Object`.
    `java.lang.String` | `getLocalPart()` Get the local part of this `QName`.
    `java.lang.String` | `getNamespaceURI()` Get the Namespace URI of this `QName`.
    `java.lang.String` | `getPrefix()` Get the prefix of this `QName`.
    `int` | `hashCode()` Generate the hash code for this `QName`.
    `java.lang.String` | `toString()` `String` representation of this `QName`.
    `static QName` | `valueOf(java.lang.String qNameAsString)` `QName` derived from parsing the formatted `String`.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### QName

          public QName(java.lang.String namespaceURI,
                       java.lang.String localPart)

      `QName` constructor specifying the Namespace URI and local part.

      If the Namespace URI is `null`, it is set to `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 `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 `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.

      Parameters:
        `namespaceURI` - Namespace URI of the `QName`
        `localPart` - local part of the `QName`
      See Also:
        `QName(String namespaceURI, String localPart, String prefix)`

    - #### QName

          public QName(java.lang.String namespaceURI,
                       java.lang.String localPart,
                       java.lang.String prefix)

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

      If the Namespace URI is `null`, it is set to `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 `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 `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.

      Parameters:
        `namespaceURI` - Namespace URI of the `QName`
        `localPart` - local part of the `QName`
        `prefix` - prefix of the `QName`

    - #### QName

          public QName(java.lang.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 `XMLConstants.NULL_NS_URI` and the prefix is set to `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 `QName(String namespaceURI, String localPart)` and `QName(String namespaceURI, String localPart, String prefix)` are preferred.

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

      Parameters:
        `localPart` - local part of the `QName`
      See Also:
        `QName(String namespaceURI, String localPart)`, `QName(String namespaceURI, String localPart, String prefix)`

  - ### Method Detail

    - #### getNamespaceURI

          public java.lang.String getNamespaceURI()

      Get the Namespace URI of this `QName`.

      Returns:
        Namespace URI of this `QName`

    - #### getLocalPart

          public java.lang.String getLocalPart()

      Get the local part of this `QName`.

      Returns:
        local part of this `QName`

    - #### getPrefix

          public java.lang.String getPrefix()

      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.

      Returns:
        prefix of this `QName`

    - #### equals

          public final boolean equals(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 `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 `Object.equals(Object)`

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `objectToTest` - the `Object` to test for equality with this `QName`
      Returns:
        `true` if the given `Object` is equal to this `QName` else `false`

    - #### hashCode

          public final int hashCode()

      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 `Object.hashCode()`.

      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        hash code for this `QName` `Object`

    - #### toString

          public java.lang.String toString()

      `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. `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 `Object.toString()`.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        `String` representation of this `QName`

    - #### valueOf

          public static QName valueOf(java.lang.String qNameAsString)

      `QName` derived from parsing the formatted `String`.

      If the `String` is `null` or does not conform to `QName.toString()` formatting, an `IllegalArgumentException` is thrown.

      The `String` MUST be in the form returned by `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. `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 `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.

      Parameters:
        `qNameAsString` - `String` representation of the `QName`
      Returns:
        `QName` corresponding to the given `String`
      See Also:
        `QName.toString()`

Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.