Element (Codename One API)

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 and Description

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

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

Constructor Summary

Constructors
Modifier	Constructor and 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

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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()` Deprecated. this uses the old vector API instead of the more modern Collection/List
`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)` Deprecated. this uses the old vector API instead of the more modern Collection/List
`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 java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - 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 Detail
  - 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 Detail
  - isTextElement
```
public boolean isTextElement()
```
    Returns true if this is a text element, false otherwise
    
    Returns:
    
    true if this is 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
  - 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
  - setParent
```
protected void setParent(Element parent)
```
    Sets this element parent, done interanlly in addChild
    
    Parameters:
    
    parent - The element's parent
  - getParent
```
public Element getParent()
```
    Returns this Element's parent
    
    Returns:
    
    this 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 - The vector to set as this Element's children
  - 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
  - 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
  - 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
    
    Overrides:
    
    toString in class Object
    
    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 - 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
    
    Specified by:
    
    iterator in interface Iterable<Element>
    
    Returns:
    
    the children iterator

Class Element

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEPTH_INFINITE

Constructor Detail

Element

Element

Element

Method Detail

isTextElement

getTagName

getAttributes

setAttribute

addChild

setParent

getParent

getNumChildren

getChildren

setChildren

setTagName

setTextElement

getChildAt

getFirstChildByTagName

getElementById

getDescendantsByTagNameAndAttribute

getDescendantsByTagName

getDescendantsByTagName

getChildrenByTagName

getTextDescendants

getTextDescendants

getTextChildren

contains

setAttribute

removeAttribute

removeAttribute

getAttributeAsInt

getAttribute

removeChildAt

getChildIndex

insertChildAt

replaceChild

getText

setText

toString

toString

hasTextChild

isEmpty

iterator