org.xins.common.xml
Class Element

java.lang.Object
  extended byorg.xins.common.xml.Element
All Implemented Interfaces:
Cloneable

public class Element
extends Object
implements Cloneable

XML Element.

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.47 $ $Date: 2010/02/06 14:51:09 $
Author:
Anthony Goubard, Ernst de Haan

Nested Class Summary
static class Element.QualifiedName
          Qualified name for an element or attribute.
 
Constructor Summary
Element(String localName)
          Creates a new Element with no namespace.
Element(String namespaceURI, String localName)
          Creates a new Element.
Element(String namespacePrefix, String namespaceURI, String localName)
          Creates a new Element.
 
Method Summary
 void addChild(Element child)
          Adds a new child element.
 Object clone()
          Clones this object.
 boolean equals(Object obj)
           
 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 the attributes of this element.
 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 getNamespacePrefix()
          Gets the namespace prefix.
 String getNamespaceURI()
          Gets the namespace URI.
 String getText()
          Gets the character content, if any.
 Element getUniqueChildElement()
          Gets the unique child of this element.
 Element getUniqueChildElement(String elementName)
          Gets the unique child of this element with the specified name.
 int hashCode()
           
 void removeAttribute(String localName)
          Removes the specified attribute.
 void removeAttribute(String namespaceURI, String localName)
          Removes the specified attribute.
 void removeChild(Element child)
          Removes a child element.
 void setAttribute(String localName, String value)
          Sets the specified attribute.
 void setAttribute(String namespaceURI, String localName, String value)
          Sets the specified attribute.
 void setAttribute(String namespacePrefix, String namespaceURI, String localName, String value)
          Sets the specified attribute.
 void setLocalName(String localName)
          Sets the local name.
 void setNamespacePrefix(String namespacePrefix)
          Sets the namespace prefix.
 void setNamespaceURI(String namespaceURI)
          Sets the namespace URI.
 void setText(String text)
          Sets the character content.
 String toString()
          Overrides the Object.toString() method to return the element as its XML representation.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Element

public Element(String localName)
        throws IllegalArgumentException
Creates a new Element with no namespace.

Parameters:
localName - the local name of the element, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

Element

public Element(String namespaceURI,
               String localName)
        throws IllegalArgumentException
Creates a new Element.

Parameters:
namespaceURI - the namespace URI for the element, can be null; an empty string is equivalent to null.
localName - the local name of the element, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

Element

public Element(String namespacePrefix,
               String namespaceURI,
               String localName)
        throws IllegalArgumentException
Creates a new Element.

Parameters:
namespacePrefix - the namespace prefix for the element, can be null; an empty string is equivalent to null.
namespaceURI - the namespace URI for the element, can be null; an empty string is equivalent to null.
localName - the local name of the element, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.1.
Method Detail

setNamespacePrefix

public void setNamespacePrefix(String namespacePrefix)
Sets the namespace prefix.

Parameters:
namespacePrefix - the namespace prefix of this element, can be null. If the value if null or an empty string, the element is consider to have no namespace prefix.
Since:
XINS 2.1.

getNamespacePrefix

public String getNamespacePrefix()
Gets the namespace prefix.

Returns:
the namespace prefix for this element, or null if there is none, but never an empty string.
Since:
XINS 2.1.

setNamespaceURI

public void setNamespaceURI(String namespaceURI)
Sets the namespace URI.

Parameters:
namespaceURI - the namespace URI of this element, can be null. If the value if null or an empty string, the element is consider to have no namespace URI.
Since:
XINS 2.1.

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.

setLocalName

public void setLocalName(String localName)
                  throws IllegalArgumentException
Sets the local name.

Parameters:
localName - the local name of this element, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

setAttribute

public void setAttribute(String localName,
                         String value)
                  throws IllegalArgumentException
Sets the specified attribute. If the value for the specified attribute is already set, then the previous value is replaced.

Parameters:
localName - the local name for the attribute, cannot be null.
value - the value for the attribute, can be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

setAttribute

public void setAttribute(String namespaceURI,
                         String localName,
                         String value)
                  throws IllegalArgumentException
Sets the specified attribute. If the value for the specified attribute is already set, then the previous value is replaced.

Parameters:
namespaceURI - the namespace URI for the attribute, can be null; an empty string is equivalent to null.
localName - the local name for the attribute, cannot be null.
value - the value for the attribute, can be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

setAttribute

public void setAttribute(String namespacePrefix,
                         String namespaceURI,
                         String localName,
                         String value)
                  throws IllegalArgumentException
Sets the specified attribute. If the value for the specified attribute is already set, then the previous value is replaced.

Parameters:
namespacePrefix - the namespace prefix for the attribute, can be null; an empty string is equivalent to null.
namespaceURI - the namespace URI for the attribute, can be null; an empty string is equivalent to null.
localName - the local name for the attribute, cannot be null.
value - the value for the attribute, can be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.1.

removeAttribute

public void removeAttribute(String localName)
                     throws IllegalArgumentException
Removes the specified attribute. If no attribute with the specified name exists, nothing happens.

Parameters:
localName - the local name for the attribute, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

removeAttribute

public void removeAttribute(String namespaceURI,
                            String localName)
                     throws IllegalArgumentException
Removes the specified attribute. If no attribute with the specified name exists, nothing happens.

Parameters:
namespaceURI - the namespace URI for the attribute, can be null; an empty string is equivalent to null.
localName - the local name for the attribute, cannot be null.
Throws:
IllegalArgumentException - if localName == null.
Since:
XINS 2.0.

getAttributeMap

public Map getAttributeMap()
Gets the attributes of this element.

Returns:
a Map (never null) which contains 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.

addChild

public void addChild(Element child)
              throws IllegalArgumentException
Adds a new child element.

Parameters:
child - the new child to add to this element, cannot be null.
Throws:
IllegalArgumentException - if child == null || child == this.
Since:
XINS 2.0.

removeChild

public void removeChild(Element child)
                 throws IllegalArgumentException
Removes a child element. If the child is not found, nothing is removed.

Parameters:
child - the child to be removed to this element, cannot be null.
Throws:
IllegalArgumentException - if child == null || child == this.
Since:
XINS 2.0.

getChildElements

public List getChildElements()
Gets the list of all child elements.

Returns:
the 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. The list cannot be modified.
Throws:
IllegalArgumentException - if name == null.

setText

public void setText(String text)
Sets the character content. The existing character content, if any, is replaced

Parameters:
text - the character content for this element, or null.
Since:
XINS 2.0.

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 with the specified name.

Parameters:
elementName - the name of the child element to get, or null if the element name is irrelevant.
Returns:
the sub-element of this element, never null.
Throws:
ParseException - if no child with the specified name was found, or if more than one child with the specified name was found.
Since:
XINS 1.4.0

getUniqueChildElement

public Element getUniqueChildElement()
                              throws ParseException
Gets the unique child of this element.

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 2.2

hashCode

public int hashCode()

equals

public boolean equals(Object obj)

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.


See http://www.xins.org/.