org.inria.ns.reflex.xml
Class QName

java.lang.Object
  extended by org.inria.ns.reflex.xml.QName
All Implemented Interfaces:
Presentable, XOperable, QNameSet

public final class QName
extends Object
implements XOperable, QNameSet, Presentable

A QName (qualified name) is an XML name built either with a prefix bound to a namespace URI and a local part, separated by a colon, or a non-colonned name that may be bound to a namespace URI.

A String is comparable to the local name of a QName that has no namespace URI.

The different parts of a QName are potentially any String, as a QName can be used for other objects than XML names.

Author:
Philippe Poulard

Field Summary
static QName QNULL
          The null QName, that has neither prefix nor local name nor namespace URI.
 
Constructor Summary
QName(Element element, String qualifiedName, boolean attributeMode)
          Creates a new instance of QName.
QName(Map namespaceURIs, String qualifiedName)
          Creates a new instance of QName.
QName(NamespaceContext namespaceContext, String qualifiedName, boolean attributeMode)
          Creates a new instance of QName.
QName(Node node)
          Creates a new instance of QName base on the namespace URI, local name, and prefix of the node given.
QName(Node node, String qualifiedName, boolean attributeMode)
          Creates a new instance of QName.
QName(String NCName)
          Creates a new instance of QName that has no namespace URI.
QName(String namespaceURI, String qualifiedName)
          Creates a new instance of QName.
QName(String namespaceURI, String prefix, String localName)
          Creates a new instance of QName.
 
Method Summary
 boolean equals(Object obj)
          Return true if the object is a QName that is equivalent to this QName, true if the object is a String that is equivalent to the local name of this QName if it has no namespace URI, false otherwise.
 String getLocalName()
          Return the local name of this QName, that can be (but shouldn't be) an empty string.
 String getNamespaceURI()
          Return the namespace URI of this QName, that can be an empty string.
 String getNamespaceURIForPrefix(String prefix)
          Return the namespace URI corresponding to the prefix, or null if the prefixes are not the same.
 String getPrefix()
          Return the prefix of this QName, that can be an empty string.
 String getQualifiedName()
          Return the qualified name, that is to say the prefix -if any- with the local name.
 XOperator getXOperator()
          Return the X-operator for a QName.
 int hashCode()
          Returns a hash code value for the QName.
 void normalize()
          If this QName has no prefix and has a namespace URI, a new prefix is generated.
 void normalize(NamespaceContext.Mutable namespaces)
          Normalize this QName regarding the given mutable namespace context.
 StringBuffer toPrettyString()
          Represents a QName as: "{" + Namespace URI + "}" + local part.
 StringBuffer toPrettyString(StringBuffer buf)
          Append the "Clark" representation of this QName to a buffer.
 String toString()
          Return this QName as a string.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

QNULL

public static final QName QNULL
The null QName, that has neither prefix nor local name nor namespace URI.

Constructor Detail

QName

public QName(Node node)
Creates a new instance of QName base on the namespace URI, local name, and prefix of the node given. If the node has no local name, the QName created is based on the full name of the node.

Parameters:
node - An element or attribute.

QName

public QName(String namespaceURI,
             String prefix,
             String localName)
Creates a new instance of QName.

Parameters:
namespaceURI - The namespace URI that qualifies the name, or null for default namespace.
prefix - The prefix used; if one find it useless, a null value may be given.
localName - The non null local name that is qualified by the namespace uri.

QName

public QName(String namespaceURI,
             String qualifiedName)
Creates a new instance of QName.

Parameters:
namespaceURI - The namespace URI that qualifies the name, or null for default namespace.
qualifiedName - The non null qualified name.

QName

public QName(String NCName)
Creates a new instance of QName that has no namespace URI.

Parameters:
NCName - The non nullNCName .

QName

public QName(Map namespaceURIs,
             String qualifiedName)
Creates a new instance of QName.

Parameters:
namespaceURIs - A set of couple of { prefix , namespace URI } used for prefix resolution.
qualifiedName - The non null qualified name.

QName

public QName(NamespaceContext namespaceContext,
             String qualifiedName,
             boolean attributeMode)
Creates a new instance of QName. Prefix resolution is done thanks to the namespace context given.

Parameters:
namespaceContext - The namespace context that resolves URI when a prefix is used.
qualifiedName - The non null qualified name.
attributeMode - true if the namespace URI must be fixed as for XML attributes, false if the namespace URI must be fixed as for elements.
  • Unqualified attributes are not bound to a namespace URI.
  • Unqualified elements are bound to the default namespace URI.

QName

public QName(Node node,
             String qualifiedName,
             boolean attributeMode)
Creates a new instance of QName. Prefix resolution is done thanks to namespaces declarations of the given node.

Parameters:
node - The node that defines the namespace for the prefix used.
qualifiedName - The non null qualified name.
attributeMode - true if the namespace URI must be fixed as for XML attributes, false if the namespace URI must be fixed as for elements.
  • Unqualified attributes are not bound to a namespace URI.
  • Unqualified elements are bound to the default namespace URI.

QName

public QName(Element element,
             String qualifiedName,
             boolean attributeMode)
Creates a new instance of QName. Prefix resolution is done thanks to namespaces declarations of the given element.

Parameters:
element - The element that defines the namespace for the prefix used.
qualifiedName - The non null qualified name.
attributeMode - true if the namespace URI must be fixed as for XML attributes, false if the namespace URI must be fixed as for elements.
  • Unqualified attributes are not bound to a namespace URI.
  • Unqualified elements are bound to the default namespace URI.
Method Detail

getNamespaceURI

public String getNamespaceURI()
Return the namespace URI of this QName, that can be an empty string.

Returns:
The non- null namespace URI.

getLocalName

public String getLocalName()
Return the local name of this QName, that can be (but shouldn't be) an empty string.

Returns:
The non- null local name.

getPrefix

public String getPrefix()
Return the prefix of this QName, that can be an empty string.

Returns:
The non- null prefix of this QName.

hashCode

public int hashCode()
Returns a hash code value for the QName. The hash code of a QName without a namespace URI is the hash code of its local name.

Overrides:
hashCode in class Object
Returns:
A hash code value for the QName.

equals

public boolean equals(Object obj)
Return true if the object is a QName that is equivalent to this QName, true if the object is a String that is equivalent to the local name of this QName if it has no namespace URI, false otherwise. When QNames are compared, the prefixes are ignored.

***

Caution

A String is assumed to be equivalent to a QName if it has no namespace URI and that its local name matches the String. This method is convenient because it compares like this a QName with a String.

On the opposite, a String compared with a QName will always give false : users should test the fields of the QName as expected, or wrap the String in a QName. It is important when QNames are used as keys in a Map.

In fact, myQName.equals( myString ) gives the same result as myQName.equals( newQName( myString ) ), but avoid the creation of a QName that has no namespace URI.

***

Overrides:
equals in class Object
Parameters:
obj - The object to compare.
Returns:
true if the object is a QName that is equivalent to this QName,false otherwise.

toString

public String toString()
Return this QName as a string.

Overrides:
toString in class Object
Returns:
The string value of this QName is the namespace URI (if any) with the local name separated with "^" (this character doesn't appear in XML names).

getQualifiedName

public String getQualifiedName()
Return the qualified name, that is to say the prefix -if any- with the local name.

Returns:
A string that looks like "prefix:localName" or "NCName".

getNamespaceURIForPrefix

public String getNamespaceURIForPrefix(String prefix)
Return the namespace URI corresponding to the prefix, or null if the prefixes are not the same.

Parameters:
prefix - The prefix to compare.
Returns:
The namespace URI corresponding to the prefix, or null if the prefixes are not the same.

getXOperator

public XOperator getXOperator()
Return the X-operator for a QName.

Specified by:
getXOperator in interface XOperable
Returns:
The singleton QName X-operator.
See Also:
XOperable.getXOperator()

normalize

public void normalize()
If this QName has no prefix and has a namespace URI, a new prefix is generated.

Specified by:
normalize in interface QNameSet
See Also:
QNameSet.normalize()

normalize

public void normalize(NamespaceContext.Mutable namespaces)
Normalize this QName regarding the given mutable namespace context.

If necessary, the prefix of this QName may be renamed. If this QName has no prefix, a default one will be provided if it has a namespace URI.

Specified by:
normalize in interface QNameSet
Parameters:
namespaces - The mutable namespace context that might be updated ; if the namespace URI of this QName is already defined and its prefix is not bound to the same namespace URI, the namespace context will be updated.
See Also:
QNameSet.normalize(NamespaceContext.Mutable)

toPrettyString

public StringBuffer toPrettyString()
Represents a QName as: "{" + Namespace URI + "}" + local part. If this QName has no namespace URI, only the local part is returned.

Specified by:
toPrettyString in interface Presentable
Returns:
The "Clark" representation of this QName.

toPrettyString

public StringBuffer toPrettyString(StringBuffer buf)
Append the "Clark" representation of this QName to a buffer.

Specified by:
toPrettyString in interface Presentable
Parameters:
buf - The buffer to append.
Returns:
The buffer appended.