org.xins.client
Class DataElement

java.lang.Object
  org.xins.client.DataElement

All Implemented Interfaces:

Cloneable

public class DataElement

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.

Since:

XINS 1.0.0

Version:

$Revision: 1.41 $ $Date: 2006/10/25 09:39:34 $

Author:

Anthony Goubard, Ernst de Haan

Nested Class Summary

static class

DataElement.QualifiedName Qualified name for an element or attribute.

Method Summary

Object	clone() Clones this object.
String	get(String localName) Deprecated. Deprecated since XINS 1.1.0. Use getAttribute(String) instead. This method has been deprecated since it used to expect/accept a combination of the namespace prefix and the local name in XINS 1.0, although that XML Namespaces were not supported yet. This method is guaranteed not to be removed before XINS 2.0.0.
String	getAttribute(DataElement.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.
Iterator	getAttributes() Deprecated. Deprecated since XINS 1.1.0. Use getAttributeMap() instead, which returns all attributes names and values and which supports XML Namespaces. This method has been deprecated since it does not support namespaces and since it returned a combination of the namespace prefix and the local name in XINS 1.0, although XML Namespaces were not supported yet. This method is guaranteed not to be removed before XINS 2.0.0.
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	getName() Deprecated. Deprecated since XINS 1.1.0. Use getLocalName() instead, which has the same functionality and behavior. This method has been deprecated since it returned a combination of the namespace prefix and the local name in XINS 1.0. This method is guaranteed not to be removed before XINS 2.0.0.
String	getNamespaceURI() Gets the namespace URI.
String	getText() Gets the character content, if any.
Element	toXMLElement() Converts this DataElement to a Element object.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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.

Since:

XINS 1.1.0

getLocalName

public String getLocalName()

Gets the local name.

Returns:

the local name of this element, cannot be null.

Since:

XINS 1.1.0

getName

public String getName()

Deprecated. Deprecated since XINS 1.1.0. Use getLocalName() instead, which has the same functionality and behavior. This method has been deprecated since it returned a combination of the namespace prefix and the local name in XINS 1.0. This method is guaranteed not to be removed before XINS 2.0.0.

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 DataElement.QualifiedName instance (not null) and each value in it is a String instance (not null).

Since:

XINS 1.1.0

getAttributes

public Iterator getAttributes()

Deprecated. Deprecated since XINS 1.1.0. Use getAttributeMap() instead, which returns all attributes names and values and which supports XML Namespaces. This method has been deprecated since it does not support namespaces and since it returned a combination of the namespace prefix and the local name in XINS 1.0, although XML Namespaces were not supported yet. This method is guaranteed not to be removed before XINS 2.0.0.

Gets the names of all attributes that do not have a namespace defined.

Returns:

an Iterator returning each attribute name as a String; or null, which indicates the DataElement has no elements.

getAttribute

public String getAttribute(DataElement.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.

Since:

XINS 1.1.0

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.

Since:

XINS 1.1.0

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.

Since:

XINS 1.1.0

get

public String get(String localName)
           throws IllegalArgumentException

Deprecated. Deprecated since XINS 1.1.0. Use getAttribute(String) instead. This method has been deprecated since it used to expect/accept a combination of the namespace prefix and the local name in XINS 1.0, although that XML Namespaces were not supported yet. This method is guaranteed not to be removed before XINS 2.0.0.

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 DataElement 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 DataElement 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.

toXMLElement

public Element toXMLElement()

Converts this DataElement to a Element object.

Returns:

the converted object, never null.

Since:

XINS 1.3.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.