org.pf.six
Class Element

java.lang.Object
  org.pf.six.Element

public class Element
extends java.lang.Object

Each element represents one tag occurance in a XML stream. The element's name corresponds to the XML tag name.

Version:

1.6

Author:

Manfred Duchrow

Field Summary

static Element[]

EMPTY_ARRAY

Constructor Summary

Element()
Initialize the new instance with default values.

Element(java.lang.String tagName)
Initialize the new instance with the given name.

Element(java.lang.String tagName, java.lang.String text)
Initialize the new instance with the given name and text.

Method Summary

void	addChild(Element childElement) Adds the given element as a child to the receiver
Element	copy() Returns a copy of the element with all child elements copied as well.
Element	deepCopy() Returns a deep copy of the element.
Element[]	find(java.lang.String tagName) Returns all sub elements with the given tag name plus this element, if it's name is equal to the given tagName.
Element[]	find(java.lang.String tagName, java.util.Map attributes) Returns all sub elements with the given tag name and the specified attribute values plus this element if it matches the tagName and attributes.
Element[]	findChildren(java.lang.String tagName) Returns all children with the given tag name.
Element[]	findChildren(java.lang.String tagName, java.util.Map attributes) Returns all children with the given tag name and the specified attribute values.
Element[]	findSubElements(java.lang.String tagName) Returns all sub elements with the given tag name.
Element[]	findSubElements(java.lang.String tagName, java.util.Map attributes) Returns all sub elements with the given tag name and the specified attribute values.
java.lang.String	getAttribute(java.lang.String attrName) Returns the value of the attribute with the given name.
java.lang.String[]	getAttributeNames() Returns the names of all attributes assigned to this element.
java.util.Map	getAttributes() Returns all attributes of the element.
Element[]	getChildren() Returns all child elements.
int	getChildrenCount() Returns the number of child elements.
java.lang.String	getName() Returns the name of the element.
java.util.Map	getNamespaceDeclarations() Returns a map with the names of namespaces as keys and the corresponding namespace URIs as values.
java.lang.String	getText() Returns the elements textual content which corresponds to the XML tag's PCDATA.
boolean	hasAttribute(java.lang.String attrName) Returns true if the element has an attribue with the given name.
boolean	hasAttributes() Returns true if the element has any attribue.
boolean	hasChildren() Returns true if the element contains any child element.
boolean	hasText() Returns true if the element has any text.
boolean	insertChildAfter(Element oldChild, Element newChild) Inserts the given newChild after the specified old child.
boolean	insertChildBefore(Element oldChild, Element newChild) Inserts the given newChild before the specified old child.
void	removeAllChildren() Removes all children of this element
void	removeAttribute(java.lang.String attrName) Removes the attribute with the specified name from the element's attribute list.
boolean	removeChild(Element childElement) Removes the given child from this element.
void	removeText() Removes the element's text content.
boolean	replaceChild(Element oldChild, Element newChild) Replaces the given oldChild by the given newChild.
void	setAttribute(java.lang.String attrName, java.lang.String value) Returns the value of the attribute with the given name.
void	setName(java.lang.String newName) Set the element's name which corresponds to its XML tag name.
void	setText(java.lang.String newText) Set the element's text.
Element	shallowCopy() Returns a shallow copy of the element, that is a new element with the same name, same attributes and same text but without children.
static Element[]	toArray(java.util.Collection elementCollection) Returns an Element array that contains all Element objects of the given collection.
static java.util.List	toList(Element[] elements) Returns an ArrayList that contains all elements of the given array.
java.lang.String	toString() Returns the element's name as a XML tag.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ARRAY

public static final Element[] EMPTY_ARRAY

Constructor Detail

Element

public Element()

Initialize the new instance with default values.

Element

public Element(java.lang.String tagName)

Initialize the new instance with the given name.

Parameters:

tagName - The name of the new element

Element

public Element(java.lang.String tagName,
               java.lang.String text)

Initialize the new instance with the given name and text.

Parameters:

tagName - The name of the new element

text - The text content of the new elemnt

Method Detail

getAttributes

public java.util.Map getAttributes()

Returns all attributes of the element. This map should not be modified, since it is not a copy. To add or remove attributes use the appropriate methods provided by Element.

toArray

public static Element[] toArray(java.util.Collection elementCollection)

Returns an Element array that contains all Element objects of the given collection. If the given collection is null or empty an empty Element array will be returned.

Parameters:

elementCollection - The collection to be converted to an array.

Throws:

java.lang.ClassCastException - If any object in the given collection is not an Element.

toList

public static java.util.List toList(Element[] elements)

Returns an ArrayList that contains all elements of the given array. If the given array is null or empty then an empty ArrayList will be returned.

Parameters:

elements - The array to convert to a list

getName

public java.lang.String getName()

Returns the name of the element. This name coresponds to the tag name in the XML representation of this element.

setName

public void setName(java.lang.String newName)

Set the element's name which corresponds to its XML tag name.

Parameters:

newName - Any valid XML tag name

getText

public java.lang.String getText()

Returns the elements textual content which corresponds to the XML tag's PCDATA.

setText

public void setText(java.lang.String newText)

Set the element's text.

Parameters:

newText - Any valid XML character data compliant to the desired encoding

getAttribute

public java.lang.String getAttribute(java.lang.String attrName)

Returns the value of the attribute with the given name. If the attribute is not set (not available) this method returns null.

setAttribute

public void setAttribute(java.lang.String attrName,
                         java.lang.String value)

Returns the value of the attribute with the given name. If the attribute is not set (not available) this method returns null.

removeAttribute

public void removeAttribute(java.lang.String attrName)

Removes the attribute with the specified name from the element's attribute list.

Parameters:

attrName - The name of the attribute to remove

getAttributeNames

public java.lang.String[] getAttributeNames()

Returns the names of all attributes assigned to this element. If the element has no attribute an empty array will be returned.

getChildrenCount

public int getChildrenCount()

Returns the number of child elements.

getChildren

public Element[] getChildren()

Returns all child elements.

hasChildren

public boolean hasChildren()

Returns true if the element contains any child element.

removeChild

public boolean removeChild(Element childElement)

Removes the given child from this element. The child itself must be in the children list. That is, comparison is done by == rather than equals().

Parameters:

childElement - The child element to be removed

Returns:

true if the child element was found and removed

removeAllChildren

public void removeAllChildren()

Removes all children of this element

removeText

public void removeText()

Removes the element's text content.

hasText

public boolean hasText()

Returns true if the element has any text.

hasAttributes

public boolean hasAttributes()

Returns true if the element has any attribue.

hasAttribute

public boolean hasAttribute(java.lang.String attrName)

Returns true if the element has an attribue with the given name.

toString

public java.lang.String toString()

Returns the element's name as a XML tag. Example: ""

Overrides:

toString in class java.lang.Object

addChild

public void addChild(Element childElement)

Adds the given element as a child to the receiver

Parameters:

childElement - The element to add

insertChildAfter

public boolean insertChildAfter(Element oldChild,
                                Element newChild)

Inserts the given newChild after the specified old child. Returns true if the old child was found and the new child successfully inserted after it.

insertChildBefore

public boolean insertChildBefore(Element oldChild,
                                 Element newChild)

Inserts the given newChild before the specified old child. Returns true if the old child was found and the new child successfully inserted after it.

replaceChild

public boolean replaceChild(Element oldChild,
                            Element newChild)

Replaces the given oldChild by the given newChild. Returns true if the old child was found and replaced.

find

public Element[] find(java.lang.String tagName)

Returns all sub elements with the given tag name plus this element, if it's name is equal to the given tagName. This method returns all matching elements down the whole hierarchy.

Returns:

An array of elements (never null)

find

public Element[] find(java.lang.String tagName,
                      java.util.Map attributes)

Returns all sub elements with the given tag name and the specified attribute values plus this element if it matches the tagName and attributes. This method returns all matching elements down the whole hierarchy.

Returns:

An array of elements (never null)

findSubElements

public Element[] findSubElements(java.lang.String tagName)

Returns all sub elements with the given tag name. That is, all direct children and children of those children and so on. It goes down recursivly the whole hierarchy.

Returns:

An array of elements (never null)

findSubElements

public Element[] findSubElements(java.lang.String tagName,
                                 java.util.Map attributes)

Returns all sub elements with the given tag name and the specified attribute values. That is, all direct children and children of those children and so on. It goes down recursivly the whole hierarchy.

findChildren

public Element[] findChildren(java.lang.String tagName)

Returns all children with the given tag name. This method returns only direct children of this element. It does not go deeper into the hierarchy.

Returns:

An array of elements (never null)

findChildren

public Element[] findChildren(java.lang.String tagName,
                              java.util.Map attributes)

Returns all children with the given tag name and the specified attribute values. This method returns only direct children of this element. It does not go deeper into the hierarchy.

Returns:

An array of elements (never null)

shallowCopy

public Element shallowCopy()

Returns a shallow copy of the element, that is a new element with the same name, same attributes and same text but without children.

deepCopy

public Element deepCopy()

Returns a deep copy of the element. That is a new element with the same name, same attributes, the same text and with a copy of all child elements.

copy

public Element copy()

Returns a copy of the element with all child elements copied as well. This is a deep copy.

See Also:

deepCopy()

getNamespaceDeclarations

public java.util.Map getNamespaceDeclarations()

Returns a map with the names of namespaces as keys and the corresponding namespace URIs as values. The map contains only those namespace definitions that are set by attributes of this element. If no namespace is declared in this element the returned map is empty.