# Class Element

java.lang.Object
com.codename1.xml.Element

All Implemented Interfaces:
  `Iterable<Element>`

Direct Known Subclasses:
  `HTMLElement`

public class Element extends Object implements Iterable<Element>
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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEPTH_INFINITE`
  A constant that can be used for the get descendants methods to denote infinite recursion

- ## Constructor Summary

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

- ## Method Summary

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

  ### Methods inherited from class Object

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

- ## Field Details

  - ### DEPTH_INFINITE

    public static final int DEPTH_INFINITE
    A constant that can be used for the get descendants methods to denote infinite recursion
    See Also:
      - Constant Field Values

- ## 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`: 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`: The tag name, or in the case of a text element the element's text

    - `isTextElement`: 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`: 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`: 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`: The attribute ID

    - `value`: 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`: 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`: 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()

    Returns the internal children vector

    ###### Returns

    the children vector

    ###### Deprecated

    this uses the old vector API instead of the more modern Collection/List

  - ### setChildren

    protected void setChildren(Vector children)

    Sets the children vector of this Element

    ###### Parameters

    - `children`: The vector to set as this Element's children

    ###### Deprecated

    this uses the old vector API instead of the more modern Collection/List

  - ### getChildAt

    public Element getChildAt(int index)

    Returns the Element's child positioned at the specified index

    ###### Parameters

    - `index`: 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`: 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`: 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`: The tag name to look for

    - `attributeName`: the attribute that must exist on the tag

    - `depth`: 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`: The tag name to look for

    - `depth`: 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`: 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`: 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`: The text to look for (null to return all text children)

    - `caseSensitive`: true to perform a case sensitive match, false to ignore case

    - `depth`: 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`: The text to look for (null to return all text children)

    - `caseSensitive`: 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`: The text to look for (null to return all text children)

    - `caseSensitive`: 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`: 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`: The attribute's name

    - `value`: 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`: 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`: The attribute ID

  - ### getAttributeAsInt

    public int getAttributeAsInt(String name, int def)

    Helper method to return the attribute as an integer

    ###### Parameters

    - `name`: the name of the attribute

    - `def`: 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`: 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`: The child's index

  - ### getChildIndex

    public int getChildIndex(Element child)

    Returns the child index

    ###### Parameters

    - `child`: 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`: The child to insert

    - `index`: The index to insert it at

  - ### replaceChild

    public void replaceChild(Element oldChild, Element newChild)

    Replaces one child with another

    ###### Parameters

    - `oldChild`: The child to replace (Must belong to this element, otherwise a call to this method will have no effect)

    - `newChild`: 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`: 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

    Overrides:
      `toString` in class `Object`

  - ### 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`: 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

    Specified by:
      `iterator` in interface `Iterable<Element>`
    Returns:
      An `Iterator` instance.