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
    Modifier and Type
    Method
    Description
    protected Object
    clone()
     
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    final Class
    getClass()
    Returns the runtime class of an object.
    int
    hashCode()
    Returns a hash code value for the object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    final void
    wait()
    Causes current thread to wait until another thread invokes the method or the method for this object.
    final void
    wait(long timeout)
    Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
    final void
    wait(long timeout, int nanos)
    Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

  • 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:

  • 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.