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