Package org.zkoss.idom

Interface Group

All Superinterfaces:
Cloneable, Item
All Known Implementing Classes:
AbstractGroup, Document, Element, EntityReference
public interface Group extends Item
Represents an item might have children. Group is also a item. Developers usually extend new classes from AbstractGroup, rather than implement this interface directly.

Design consideration: we don't support removeChildren and setChild or alike, because they can be done easily with List's methods and getAttributeIndex.

Author:
tomyeh
See Also:

  • Method Details

    • getChildren

      List<Item> getChildren()
      Gets all children.

      The returned list is "live". Any modification to it affects the node. On the other hand, getElements(String) returns a copy.

      Unlike JDOM, it won't coalesce adjacent children automatically since it might violate the caller's expectation about List. Rather, we provide coalesce to let caller do the merging explicitly. Note: when building a iDOM tree from a source (SAXBuilder.build), coalesce() will be invoked automatically.

      Note: not all items supports children. If this item doesn't, it returns an empty list. And, if any invocation tries to add vertices to the returned list will cause UnsupportOperationException.

    • detachChildren

      List<Item> detachChildren()
      Detaches all children and returns them in a list.

      Note: you cannot add children to anther Group by doing group.addAll(e.getChildren()), because you have to detach them first. Then, you could use this method:
      group.addAll(e.detachChildren());

    • coalesce

      int coalesce(boolean recursive)
      Coalesces children if they are siblings with the same type instances of Textual, Textual.isCoalesceable returns true.

      SAXBuilder.build will do the merging automatically.

      Parameters:
      recursive - true to coalesce all descendants; false to coalesce only the direct children

    • getElementIndex

      int getElementIndex(int indexFrom, String namespace, String name, int mode)
      Gets the index of the Element-type first child that match the specified criteria.

      Note: only Element-type children are returned, since others have no name.

      Parameters:
      indexFrom - the index to start searching from; 0 for beginning
      namespace - the namespace URI if FIND_BY_PREFIX is not specified; the namespace prefix if FIND_BY_PREFIX specified; null to ignore
      name - the local name if FIND_BY_TAGNAME is not specified; the tag name if FIND_BY_TAGNAME specified; null to ignore
      mode - the search mode; zero or any combination of Item.FIND_xxx, except FIND_RECURSIVE
      Returns:
      the index if found; -1 if not found

    • getElementIndex

      int getElementIndex(int indexFrom, String tname)
      Gets the index of the first Element-type child with the specified name.

      Note: only Element-type children are returned, since others have no name. 

      getChildren().add(getElementIndex(0, "pre:name"),
    new Element("pre:another"));
      Parameters:
      indexFrom - the index to start searching from; 0 for beginning
      tname - the tag name (i.e., Namespaceable.getName)
      Returns:
      the index if found; -1 if not found

    • getElementValue

      String getElementValue(String namespace, String name, int mode, boolean trim)
      Gets the value of the first Element-type child that matches the giving criteria, with a trimming option.
      Parameters:
      namespace - the namespace URI if FIND_BY_PREFIX is not specified; the namespace prefix if FIND_BY_PREFIX specified; null to ignore
      name - the local name if FIND_BY_TAGNAME is not specified; the tag name if FIND_BY_TAGNAME specified; null to ignore
      Returns:
      the value of the first Element-type child ; null if not found

    • getElementValue

      String getElementValue(String tname, boolean trim)
      Gets the text of the first Element-type child with the tag name, with a trimming option.
      Parameters:
      tname - the tag name (i.e., Namespaceable.getName)
      Returns:
      the text of the first Element-type child with the tag name; null if not found

    • getElement

      Element getElement(String namespace, String name, int mode)
      Gets the first Element-type child that matches the giving criteria.

      Note: only Element-type children are returned. Depending on the mode, the searching is usually linear -- take O(n) to complete.

      Parameters:
      namespace - the namespace URI if FIND_BY_PREFIX is not specified; the namespace prefix if FIND_BY_PREFIX specified; null to ignore
      name - the local name if FIND_BY_TAGNAME is not specified; the tag name if FIND_BY_TAGNAME specified; null to ignore
      mode - the search mode; zero or any combination of FIND_xxx.
      Returns:
      the found element; null if not found or not supported

    • getElement

      Element getElement(String tname)
      Gets the first Element-type child with the tag name. It is the same as childOf(nsURI, lname, null, 0).

      Note: only Element-type children are returned. Also, we did some optimization for this method so its access time is nearly constant.

      Parameters:
      tname - the tag name (i.e., Namespaceable.getName)
      Returns:
      the found element; null if not found or not supported

    • getElements

      List<Element> getElements(String namespace, String name, int mode)
      Gets a readonly list of Element-type children that match the giving criteria.

      Unlike Element.getElementsByTagName(java.lang.String), this method only returns child elements, excluding grand children and other descendants.

      The returned list is a 'live-facade' of the real ones, so the performance is good, and any modification to getChildren() will affect it.

      Note: only Element-type children are returned. Depending on the mode, the searching is usually linear -- take O(n) to complete.

      Parameters:
      namespace - the namespace URI if FIND_BY_PREFIX is not specified; the namespace prefix if FIND_BY_PREFIX specified; null to ignore
      name - the local name if FIND_BY_TAGNAME is not specified; the tag name if FIND_BY_TAGNAME specified; null to ignore
      mode - the search mode; zero or any combination of FIND_xxx.
      Returns:
      a read-only list containing all matched children; an empty list if not found or not supported

    • getElements

      List<Element> getElements(String tname)
      Gets a readonly list of children with the tag name.

      Unlike Element.getElementsByTagName(java.lang.String), this method only returns child elements, excluding grand children and other descendants.

      The returned list is a 'live-facade' of the real ones, so the performance is good, and any modification to getChildren() will affect it.

      Note: only Element-type children are returned. Also, we did some optimization for this method so its access time is nearly constant.

      Parameters:
      tname - the tag name (i.e., Namespaceable.getName)

    • getElementNames

      Set<String> getElementNames()
      Returns a readonly set of names of element children. Then, you could use getElements(java.lang.String, java.lang.String, int) to get elements.

      The returned list is a 'live-facade' of the real ones, so the performance is good, and any modification to getChildren() will affect it.

      See Also:

    • getElements

      List<Element> getElements()
      Returns a cloned copy of all element children

      Unlike getChildren() and getElementNames(), the returned list is NOT a 'live-facade' of the real ones.

      See Also: