public class Element

  1. Object
  2. Element

ImplementsIterable<Element>

Known subtypesHTMLElement

The Element class defines a single XML element with its attributes and children. Due to its hierarchial nature, this class can be used for a single “leaf” Element, for more complex elements (with child elements), and up to describing the entire document.

Fields

public static final int DEPTH_INFINITE = 2147483647A constant that can be used for the get descendants methods to denote infinite recursion

Constructors

protected Element()Constructs and Element without specifying a name This can be used by subclasses that do not require name assigments.
public Element(String tagName)Constructs an Element with the specified name
public Element(String tagName, boolean isTextElement)Constructs an Element (or a text element) with the specified name or text.

Methods

public boolean isTextElement()Returns true if this is a text element, false otherwise
protected void setTextElement(boolean textElement)Sets this element as a text element
public String getTagName()Returns this Element’s tag name
protected void setTagName(String name)Sets the name or text (for text elements) of this tag
public Hashtable getAttributes()Returns the attributes Hashtable
protected void setAttribute(Object id, String value)Adds the specified attribute and value to this Element if it is supported for the Element and has a valid value.
public void addChild(Element childElement)Adds the specified Element as a child to this element.
public Element getParent()Returns this Element’s parent
protected void setParent(Element parent)Sets this element parent, done interanlly in addChild
public int getNumChildren()Returns the number of this Element’s children
protected Vector getChildren()Deprecated Returns the internal children vector
protected void setChildren(Vector children)Deprecated Sets the children vector of this Element
public Element getChildAt(int index)Returns the Element’s child positioned at the specified index
public Element getFirstChildByTagName(String name)Returns an Element’s child by a tag name
public Element getElementById(String id)Returns the element with the specified ID
public Vector getDescendantsByTagNameAndAttribute(String name, String attributeName, int depth)Returns all descendants with the specified tag name and the none empty attribute
public Vector getDescendantsByTagName(String name, int depth)Returns all descendants with the specified tag name
public Vector getDescendantsByTagName(String name)Returns all descendants with the specified tag name
public Vector getChildrenByTagName(String name)Returns all children with the specified tag name
public Vector getTextDescendants(String text, boolean caseSensitive, int depth)Returns all text descendants containing the specified text
public Vector getTextDescendants(String text, boolean caseSensitive)Returns all text descendants containing the specified text
public Vector getTextChildren(String text, boolean caseSensitive)Returns all children with the specified text
public boolean contains(Element element)Returns true if the specified element is contained in this element’s hierarchy (meaning it is one of its descendants)
public int setAttribute(String attribute, String value)Adds the specified attribute and value to this Element if it is supported for the Element and has a valid value.
public void removeAttribute(String attribute)Removes the specified attribute
protected void removeAttribute(Object id)Removes the specified attribute if it exist in this Element This method allows creating a key that is non-string to be used by subclasses that optimize attributes retrieval
public int getAttributeAsInt(String name, int def)Helper method to return the attribute as an integer
public String getAttribute(String name)Returns the attribute value by its name (or null if it wasn’t defined for this element)
public void removeChildAt(int index)Removes the child at the given index
public int getChildIndex(Element child)Returns the child index
public void insertChildAt(Element child, int index)Inserts the given child at the specified index
public void replaceChild(Element oldChild, Element newChild)Replaces one child with another
public String getText()Returns the text of this element (for text elements only)
public void setText(String str)Sets the text of this element to the specified string (For text elements only)
public String toString()Returns a printable string representing this element
public String toString(String spacing)A recursive method for creating a printout of a full tag with its entire hierarchy.
public boolean hasTextChild()Determines whether or not this Element has any text children.
public boolean isEmpty()Determines whether or not this Element has no children.
public Iterator<Element> iterator()Iterable for children of this entry making tree walking easier, this makes for(Element child : base) {} possible

Inherited methods

From Object

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

From Iterable

forEach

Field details

DEPTH_INFINITE

public static final int DEPTH_INFINITE = 2147483647
A constant that can be used for the get descendants methods to denote infinite recursion

Constructor details

Element

protected Element()
Constructs and Element without specifying a name This can be used by subclasses that do not require name assigments.

Element

public Element(String tagName)
Constructs an Element with the specified name

Parameters

tagName String
The tag name

Element

public Element(String tagName, boolean isTextElement)
Constructs an Element (or a text element) with the specified name or text.

Parameters

tagName String
The tag name, or in the case of a text element the element’s text
isTextElement boolean
true for a text element, false otherwise

Method details

isTextElement

public boolean isTextElement()
Returns true if this is a text element, false otherwise

Returns

true if this is a text element, false otherwise

setTextElement

protected void setTextElement(boolean textElement)
Sets this element as a text element

Parameters

textElement boolean
true to set this as a text element, false otherwise

getTagName

public String getTagName()
Returns this Element’s tag name

Returns

the Element’s tag name

Throws

IllegalStateException
if this is a text element

setTagName

protected void setTagName(String name)
Sets the name or text (for text elements) of this tag

Parameters

name String
The name or text of this tag

getAttributes

public Hashtable getAttributes()
Returns the attributes Hashtable

Returns

the attributes Hashtable

setAttribute

protected void setAttribute(Object id, String value)
Adds the specified attribute and value to this Element if it is supported for the Element and has a valid value. This method allows creating a key that is non-string to be used by subclasses that optimize attributes retrieval

Parameters

id Object
The attribute ID
value String
The attribute value

addChild

public void addChild(Element childElement)
Adds the specified Element as a child to this element. If the specified element was found to be unsupported (i.e. it’s ID is TAG_UNSUPPORTED, it is not added.

Parameters

childElement Element
The child element

getParent

public Element getParent()
Returns this Element’s parent

Returns

this Element’s parent

setParent

protected void setParent(Element parent)
Sets this element parent, done interanlly in addChild

Parameters

parent Element
The element’s parent

getNumChildren

public int getNumChildren()
Returns the number of this Element’s children

Returns

the number of this Element’s children

getChildren

protected Vector getChildren()
Deprecated. this uses the old vector API instead of the more modern Collection/List
Returns the internal children vector

Returns

the children vector

setChildren

protected void setChildren(Vector children)
Deprecated. this uses the old vector API instead of the more modern Collection/List
Sets the children vector of this Element

Parameters

children Vector
The vector to set as this Element’s children

getChildAt

public Element getChildAt(int index)
Returns the Element’s child positioned at the specified index

Parameters

index int
The requested index

Returns

child number index of this ELement

Throws

ArrayIndexOutOfBoundsException
if the index is bigger than the children’s count or smaller than 0

getFirstChildByTagName

public Element getFirstChildByTagName(String name)
Returns an Element’s child by a tag name

Parameters

name String
The child’s tag name

Returns

the first child with the specified name, or null if not found

getElementById

public Element getElementById(String id)
Returns the element with the specified ID

Parameters

id String
The id to find

Returns

An element with the id, or null if none found

getDescendantsByTagNameAndAttribute

public Vector getDescendantsByTagNameAndAttribute(String name, String attributeName, int depth)
Returns all descendants with the specified tag name and the none empty attribute

Parameters

name String
The tag name to look for
attributeName String
the attribute that must exist on the tag
depth int
The search depth (1 - children, 2 - grandchildren …. DEPTH_INFINITE - for all descendants)

Returns

A vector containing descendants with the specified tag name

getDescendantsByTagName

public Vector getDescendantsByTagName(String name, int depth)
Returns all descendants with the specified tag name

Parameters

name String
The tag name to look for
depth int
The search depth (1 - children, 2 - grandchildren …. DEPTH_INFINITE - for all descendants)

Returns

A vector containing descendants with the specified tag name

getDescendantsByTagName

public Vector getDescendantsByTagName(String name)
Returns all descendants with the specified tag name

Parameters

name String
The tag name to look for

Returns

A vector containing descendants with the specified tag name

getChildrenByTagName

public Vector getChildrenByTagName(String name)
Returns all children with the specified tag name

Parameters

name String
The tag name to look for

Returns

A vector containing children with the specified tag name

getTextDescendants

public Vector getTextDescendants(String text, boolean caseSensitive, int depth)
Returns all text descendants containing the specified text

Parameters

text String
The text to look for (null to return all text children)
caseSensitive boolean
true to perform a case sensitive match, false to ignore case
depth int
The search depth (1 - children, 2 - grandchildren …. DEPTH_INFINITE - for all descendants)

Returns

A vector containing descendants containing the specified text

getTextDescendants

public Vector getTextDescendants(String text, boolean caseSensitive)
Returns all text descendants containing the specified text

Parameters

text String
The text to look for (null to return all text children)
caseSensitive boolean
true to perform a case sensitive match, false to ignore case

Returns

A vector containing decensants containing the specified text

getTextChildren

public Vector getTextChildren(String text, boolean caseSensitive)
Returns all children with the specified text

Parameters

text String
The text to look for (null to return all text children)
caseSensitive boolean
true to perform a case sensitive match, false to ignore case

Returns

A vector containing children containing the specified text

contains

public boolean contains(Element element)
Returns true if the specified element is contained in this element’s hierarchy (meaning it is one of its descendants)

Parameters

element Element
The element to look for

Returns

true if this element contains the specified element, false otherwise

setAttribute

public int setAttribute(String attribute, String value)
Adds the specified attribute and value to this Element if it is supported for the Element and has a valid value.

Parameters

attribute String
The attribute’s name
value String
The attribute’s value

Returns

a positive error code or -1 if attribute is supported and valid

removeAttribute

public void removeAttribute(String attribute)
Removes the specified attribute

Parameters

attribute String
The attribute to remove

removeAttribute

protected void removeAttribute(Object id)
Removes the specified attribute if it exist in this Element This method allows creating a key that is non-string to be used by subclasses that optimize attributes retrieval

Parameters

id Object
The attribute ID

getAttributeAsInt

public int getAttributeAsInt(String name, int def)
Helper method to return the attribute as an integer

Parameters

name String
the name of the attribute
def int
default value

Returns

return value

getAttribute

public String getAttribute(String name)
Returns the attribute value by its name (or null if it wasn’t defined for this element)

Parameters

name String
The attribute id

Returns

the attribute value by its name (or null if it wasn’t defined for this element)

removeChildAt

public void removeChildAt(int index)
Removes the child at the given index

Parameters

index int
The child’s index

getChildIndex

public int getChildIndex(Element child)
Returns the child index

Parameters

child Element
The child element to look for

Returns

The child position, or -1 if the child does not belong to this element.

insertChildAt

public void insertChildAt(Element child, int index)
Inserts the given child at the specified index

Parameters

child Element
The child to insert
index int
The index to insert it at

replaceChild

public void replaceChild(Element oldChild, Element newChild)
Replaces one child with another

Parameters

oldChild Element
The child to replace (Must belong to this element, otherwise a call to this method will have no effect)
newChild Element
The child to replace it with

getText

public String getText()
Returns the text of this element (for text elements only)

Returns

the text of this element (for text elements only)

Throws

IllegalStateException
if this is not a text element

setText

public void setText(String str)
Sets the text of this element to the specified string (For text elements only)

Parameters

str String
The text to set

Throws

IllegalStateException
if this is not a text element

toString

public String toString()
Returns a printable string representing this element

Returns

a printable string representing this element

toString

public String toString(String spacing)
A recursive method for creating a printout of a full tag with its entire hierarchy. This is used by the public method toString().

Parameters

spacing String
Increased by one in each recursion phase to provide with indentation

Returns

the printout of this tag

hasTextChild

public boolean hasTextChild()
Determines whether or not this Element has any text children.

Returns

true if any of this Elements children are text Elements.

isEmpty

public boolean isEmpty()
Determines whether or not this Element has no children.

Returns

true if this Element has no children.

iterator

public Iterator<Element> iterator()
Iterable for children of this entry making tree walking easier, this makes for(Element child : base) {} possible

Returns

the children iterator