QName (Java SE 26 & JDK 26)
Description: declaration: module: java.xml, package: javax.xml.namespace, class: QName
Keywords: javax.xml.namespace.QName class

# Class QName

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

All Implemented Interfaces:
  `Serializable`

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.

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
See Also:
  - XML Schema Part2: Datatypes specification
  - Namespaces in XML
  - Serialized Form

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final boolean`
  `equals(Object objectToTest)`
  Test this `QName` for equality with another `Object`.
  `String`
  `getLocalPart()`
  Get the local part of this `QName`.
  `String`
  `getNamespaceURI()`
  Get the Namespace URI of this `QName`.
  `String`
  `getPrefix()`
  Get the prefix of this `QName`.
  `final int`
  `hashCode()`
  Generate the hash code for this `QName`.
  `String`
  `toString()`
  Returns the string representation of this `QName`.
  `static QName`
  `valueOf(String qNameAsString)`
  Returns a `QName` from its string representation.

  ### Methods declared in class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### QName

    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 `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`
    Throws:
      `IllegalArgumentException` - When `localPart` is `null`
    See Also:
      - `QName(String namespaceURI, String localPart, String prefix)`

  - ### QName

    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 `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`
    Throws:
      `IllegalArgumentException` - When `localPart` or `prefix` is `null`

  - ### QName

    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 `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`
    Throws:
      `IllegalArgumentException` - When `localPart` is `null`
    See Also:
      - `QName(String namespaceURI, String localPart)`
      - `QName(String namespaceURI, String localPart, String prefix)`

- ## Method Details

  - ### getNamespaceURI

    public String getNamespaceURI()

    Get the Namespace URI of this `QName`.

    Returns:
      Namespace URI of this `QName`

  - ### getLocalPart

    public String getLocalPart()

    Get the local part of this `QName`.

    Returns:
      local part of this `QName`

  - ### getPrefix

    public 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(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 `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`
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### 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 `Object`
    Returns:
      hash code for this `QName` `Object`
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(Object)`

  - ### toString

    public String toString()
    Returns the string representation of this `QName`. The format is:

            {NamespaceURI}LocalPart

    If `NamespaceURI` is `null`, only `LocalPart` is returned.
    Overrides:
      `toString` in class `Object`
    API Note:
      The `Prefix` is not returned in the string representation.
    Returns:
      the string representation of this `QName`

  - ### valueOf

    public static QName valueOf(String qNameAsString)
    Returns a `QName` from its string representation. The string representation must be in the format returned by `toString()`:

            {NamespaceURI}LocalPart

    Since the `Prefix` is not represented in the string form, it will be set to `XMLConstants.DEFAULT_NS_PREFIX`.
    API Note:
      This method does not perform full validation of the resulting `QName`. The `NamespaceURI` is not validated as a URI reference. The `LocalPart` is not validated as a NCName as specified in Namespaces in XML.
    Parameters:
      `qNameAsString` - the string representation of the `QName`
    Returns:
      a `QName` from its string representation
    Throws:
      `IllegalArgumentException` - if `qNameAsString` is `null` or malformed
    See Also:
      - `QName.toString()`