Package eu.maveniverse.domtrip

Class QName

java.lang.Object

eu.maveniverse.domtrip.QName

public final class QName
extends java.lang.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:

Element, NamespaceContext, NamespaceResolver

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	NO_NAMESPACE	Empty namespace URI constant for elements not in any namespace

Method Summary

Modifier and Type	Method	Description
boolean	equals(java.lang.Object obj)
int	hashCode()
boolean	hasNamespace()	Checks if this QName has a namespace.
boolean	hasPrefix()	Checks if this QName has a prefix.
java.lang.String	localName()	Gets the local name.
boolean	matches(QName other)	Checks if this QName matches the given QName.
boolean	matches(java.lang.String namespaceURI, java.lang.String localName)	Checks if this QName matches the given namespace URI and local name.
java.lang.String	namespaceURI()	Gets the namespace URI.
static QName	of(java.lang.String localName)	Creates a QName for an element with no namespace.
static QName	of(java.lang.String namespaceURI, java.lang.String localName)	Creates a QName with the specified namespace URI and local name.
static QName	of(java.lang.String namespaceURI, java.lang.String localName, java.lang.String prefix)	Creates a QName with the specified namespace URI, local name, and preferred prefix.
static QName	parse(java.lang.String qualifiedName)	Parses a qualified name string into a QName.
java.lang.String	prefix()	Gets the namespace prefix.
java.lang.String	qualifiedName()	Gets the qualified name (prefix:localName or just localName).
java.lang.String	toString()
QName	withNamespaceURI(java.lang.String newNamespaceURI)	Creates a new QName with the same local name and prefix but different namespace URI.
QName	withPrefix(java.lang.String newPrefix)	Creates a new QName with the same namespace URI and local name but different prefix.

Methods inherited from class java.lang.Object

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

Field Detail

NO_NAMESPACE

public static final java.lang.String NO_NAMESPACE

Empty namespace URI constant for elements not in any namespace

See Also:

Constant Field Values

Method Detail

of

public static QName of(java.lang.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(java.lang.String namespaceURI,
                       java.lang.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(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.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(java.lang.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 java.lang.String namespaceURI()

Gets the namespace URI.

Returns:

the namespace URI, or empty string if not in any namespace

localName

public java.lang.String localName()

Gets the local name.

Returns:

the local name, never null or empty

prefix

public java.lang.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 java.lang.String qualifiedName()

Gets the qualified name (prefix:localName or just localName).

Returns:

the qualified name

withNamespaceURI

public QName withNamespaceURI(java.lang.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(java.lang.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(java.lang.String namespaceURI,
                       java.lang.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(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object