org.xins.common.xml
Class Element

java.lang.Object
  org.xins.common.xml.Element

All Implemented Interfaces:

Cloneable

public class Element

extends Object

implements Cloneable

Element in a XINS result data section.

Note that this class is not thread-safe. It should not be used from different threads at the same time. This applies even to read operations.

Note that the namespace URIs and local names are not checked for validity in this class.

Instances of this class cannot be created directly, using a constructor. Instead, use ElementBuilder to build an XML element, or ElementParser to parse an XML string.

Since:

XINS 1.1.0

Version:

$Revision: 1.21 $ $Date: 2006/10/26 08:21:20 $

Author:

Anthony Goubard, Ernst de Haan

Nested Class Summary

static class

Element.QualifiedName Qualified name for an element or attribute.

Method Summary

Object	clone() Clones this object.
String	getAttribute(Element.QualifiedName qn) Gets the value of the attribute with the qualified name.
String	getAttribute(String localName) Gets the value of an attribute that has no namespace.
String	getAttribute(String namespaceURI, String localName) Gets the value of the attribute with the specified namespace and local name.
Map	getAttributeMap() Gets an unmodifiable view of all attributes.
List	getChildElements() Gets the list of all child elements.
List	getChildElements(String name) Gets the list of child elements that match the specified name.
String	getLocalName() Gets the local name.
String	getNamespaceURI() Gets the namespace URI.
String	getText() Gets the character content, if any.
Element	getUniqueChildElement(String elementName) Gets the unique child of this element.
String	toString() Overrides the Object.toString() method to return the element as its XML representation.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getNamespaceURI

public String getNamespaceURI()

Gets the namespace URI.

Returns:

the namespace URI for this element, or null if there is none, but never an empty string.

getLocalName

public String getLocalName()

Gets the local name.

Returns:

the local name of this element, cannot be null.

getAttributeMap

public Map getAttributeMap()

Gets an unmodifiable view of all attributes.

Returns:

an unmodifiable Map (never null) which is a view on all the attributes; each key in the Map is a Element.QualifiedName instance (not null) and each value in it is a String instance (not null).

getAttribute

public String getAttribute(Element.QualifiedName qn)
                    throws IllegalArgumentException

Gets the value of the attribute with the qualified name. If the qualified name does not specify a namespace, then only an attribute that does not have a namespace will match.

Parameters:

qn - a combination of an optional namespace and a mandatory local name, or null.

Returns:

the value of the attribute that matches the specified namespace and local name, or null if such an attribute is either not set or set to null.

Throws:

IllegalArgumentException - if qn == null.

getAttribute

public String getAttribute(String namespaceURI,
                           String localName)
                    throws IllegalArgumentException

Gets the value of the attribute with the specified namespace and local name. The namespace is optional. If the namespace is not given, then only an attribute that does not have a namespace will match.

Parameters:

namespaceURI - the namespace URI for the attribute, can be null; an empty string is equivalent to null; if specified this string must be a valid namespace URI.

localName - the local name of the attribute, cannot be null.

Returns:

the value of the attribute that matches the specified namespace and local name, or null if such an attribute is either not set or set to null.

Throws:

IllegalArgumentException - if localName == null.

getAttribute

public String getAttribute(String localName)
                    throws IllegalArgumentException

Gets the value of an attribute that has no namespace.

Parameters:

localName - the local name of the attribute, cannot be null.

Returns:

the value of the attribute that matches the specified local name and has no namespace defined, or null if the attribute is either not set or set to null.

Throws:

IllegalArgumentException - if localName == null.

getChildElements

public List getChildElements()

Gets the list of all child elements.

Returns:

an unmodifiable List containing all child elements; each element in the list is another Element instance; never null.

getChildElements

public List getChildElements(String name)
                      throws IllegalArgumentException

Gets the list of child elements that match the specified name.

Parameters:

name - the name for the child elements to match, cannot be null.

Returns:

a List containing each child element that matches the specified name as another Element instance; never null.

Throws:

IllegalArgumentException - if name == null.

getText

public String getText()

Gets the character content, if any.

Returns:

the character content of this element, or null if no text has been specified for this element.

getUniqueChildElement

public Element getUniqueChildElement(String elementName)
                              throws ParseException

Gets the unique child of this element.

Parameters:

elementName - the name of the child element to get, or null if the parent have a unique child.

Returns:

the sub-element of this element, never null.

Throws:

ParseException - if no child was found or more than one child was found.

Since:

XINS 1.4.0

clone

public Object clone()

Clones this object. The clone will have the same namespace URI and local name and equivalent attributes, children and character content.

Returns:

a new clone of this object, never null.

toString

public String toString()

Overrides the Object.toString() method to return the element as its XML representation.

Returns:

the XML representation of this element without the XML declaration, never null.