org.pf.six
Class Element

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

public class Element
extends java.lang.Object

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

Version:

2.0

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[]	getAttributeLocalNames() Returns the names of all attributes assigned to this element.
java.lang.String[]	getAttributeNames() Returns the names of all attributes assigned to this element.
java.util.Map	getAttributes() Returns all attributes of this element.
Element[]	getChildren() Returns all child elements.
int	getChildrenCount() Returns the number of child elements.
Element	getFirstChild() Returns the first child element or null if there is no child element.
java.lang.String	getLocalName() Returns the local name of this element.
java.lang.String	getName() Returns the name of the element.
java.lang.String	getNamePrefix()
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) Sets 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 element

Method Detail

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

getLocalName

public java.lang.String getLocalName()

Returns the local name of this element. That is, without a namespace prefix.

getNamePrefix

public java.lang.String getNamePrefix()

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.

Parameters:

attrName - The name of the attribute including a namespace prefix if applicable

setAttribute

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

Sets the value of the attribute with the given name. If the attribute exists already its value will be changed to the new one.

Parameters:

attrName - The name of the attribute including a namespace prefix if applicable

value - The value to assign to this attribute

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 (including namespace prefix)

getAttributes

public java.util.Map getAttributes()

Returns all attributes of this element. This returned map may be modified, since it is a copy. To add or remove attributes will not change the attributes of this element. by Element.

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. The returned names are qualified names, that means they may contain namespace prefixes.

getAttributeLocalNames

public java.lang.String[] getAttributeLocalNames()

Returns the names of all attributes assigned to this element. If the element has no attribute an empty array will be returned. The returned names are local names, that means they don't contain namespace prefixes.

getChildrenCount

public int getChildrenCount()

Returns the number of child elements.

getChildren

public Element[] getChildren()

Returns all child elements.

getFirstChild

public Element getFirstChild()

Returns the first child element or null if there is no child element.

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.