Class QName

java.lang.Object
eu.maveniverse.domtrip.QName
public final class QName extends Object
Represents a qualified XML name with namespace URI, local name, and optional prefix.

QName provides a clean, type-safe way to work with XML namespaces, eliminating the need to pass namespace URI and local name as separate parameters throughout the API. It supports both prefixed and unprefixed names, and handles the common case of elements in no namespace.

Usage Examples:

// Simple local name (no namespace)
QName version = QName.of("version");

// Namespaced element
QName dependency = QName.of("http://maven.apache.org/POM/4.0.0", "dependency");

// With preferred prefix
QName soapEnvelope = QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Envelope", "soap");

// Parse from qualified name
QName parsed = QName.parse("soap:Envelope");  // prefix:localName

Namespace Handling:

  • No Namespace - Elements with no namespace URI
  • Default Namespace - Elements in a namespace without prefix
  • Prefixed Namespace - Elements with explicit namespace prefix
See Also:

  • Field Details

    • NO_NAMESPACE

      public static final String NO_NAMESPACE
      Empty namespace URI constant for elements not in any namespace
      See Also:

  • Method Details

    • of

      public static QName of(String localName) throws DomTripException
      Creates a QName for an element with no namespace.
      Parameters:
      localName - the local name
      Returns:
      a new QName with no namespace
      Throws:
      DomTripException - if localName is null or empty

    • of

      public static QName of(String namespaceURI, String localName) throws DomTripException
      Creates a QName with the specified namespace URI and local name.
      Parameters:
      namespaceURI - the namespace URI
      localName - the local name
      Returns:
      a new QName
      Throws:
      DomTripException - if localName is null or empty

    • of

      public static QName of(String namespaceURI, String localName, String prefix) throws DomTripException
      Creates a QName with the specified namespace URI, local name, and preferred prefix.
      Parameters:
      namespaceURI - the namespace URI
      localName - the local name
      prefix - the preferred namespace prefix
      Returns:
      a new QName
      Throws:
      DomTripException - if localName is null or empty

    • parse

      public static QName parse(String qualifiedName) throws DomTripException
      Parses a qualified name string into a QName.

      Supports the following formats:

      • localName - Element with no namespace
      • prefix:localName - Element with namespace prefix

      Note: This method only parses the syntactic structure. The actual namespace URI must be resolved using a NamespaceContext.

      Parameters:
      qualifiedName - the qualified name to parse
      Returns:
      a new QName with the parsed prefix and local name
      Throws:
      DomTripException - if qualifiedName is null, empty, or invalid

    • namespaceURI

      public String namespaceURI()
      Gets the namespace URI.
      Returns:
      the namespace URI, or empty string if not in any namespace

    • localName

      public String localName()
      Gets the local name.
      Returns:
      the local name, never null or empty

    • prefix

      public String prefix()
      Gets the namespace prefix.
      Returns:
      the namespace prefix, or null if no prefix

    • hasNamespace

      public boolean hasNamespace()
      Checks if this QName has a namespace.
      Returns:
      true if this QName has a non-empty namespace URI

    • hasPrefix

      public boolean hasPrefix()
      Checks if this QName has a prefix.
      Returns:
      true if this QName has a non-null prefix

    • qualifiedName

      public String qualifiedName()
      Gets the qualified name (prefix:localName or just localName).
      Returns:
      the qualified name

    • withNamespaceURI

      public QName withNamespaceURI(String newNamespaceURI) throws DomTripException
      Creates a new QName with the same local name and prefix but different namespace URI.
      Parameters:
      newNamespaceURI - the new namespace URI
      Returns:
      a new QName with the updated namespace URI
      Throws:
      DomTripException

    • withPrefix

      public QName withPrefix(String newPrefix) throws DomTripException
      Creates a new QName with the same namespace URI and local name but different prefix.
      Parameters:
      newPrefix - the new prefix
      Returns:
      a new QName with the updated prefix
      Throws:
      DomTripException

    • matches

      public boolean matches(String namespaceURI, String localName)
      Checks if this QName matches the given namespace URI and local name.
      Parameters:
      namespaceURI - the namespace URI to match
      localName - the local name to match
      Returns:
      true if both namespace URI and local name match

    • matches

      public boolean matches(QName other)
      Checks if this QName matches the given QName.

      Two QNames match if they have the same namespace URI and local name. The prefix is not considered for matching.

      Parameters:
      other - the QName to match against
      Returns:
      true if namespace URI and local name match

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object