Package org.zkoss.idom.impl

## Class AbstractGroup

- java.lang.Object
- - org.zkoss.idom.impl.AbstractItem
  - - org.zkoss.idom.impl.AbstractGroup

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `org.w3c.dom.Node`, `Group`, `Item`
  Direct Known Subclasses:
    `Document`, `Element`, `EntityReference`

      public abstract class AbstractGroup
      extends AbstractItem
      implements Group

  A semi-implemented item for group. A group is a item that has child items.

  The default implementation of newChildren is for the semantic of Element. A deriving class has to re-implement it, if it is not applicable. Example, Document.

  Author:
    tomyeh
  See Also:
    `Item`, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `AbstractGroup.ChildArray` | The array to hold children.
    `protected static class` | `AbstractGroup.ElementMap` | Stores a 'cached' map of child elements to speed up the access.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.List<Item>` | `_children` | The list of the children.

    - ### Fields inherited from interface org.zkoss.idom.Item

      `FIND_BY_PREFIX, FIND_BY_REGEX, FIND_BY_TAGNAME, FIND_IGNORE_CASE, FIND_RECURSIVE`

    - ### Fields inherited from interface org.w3c.dom.Node

      `ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractGroup()` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `anyElement()` |
    `org.w3c.dom.Node` | `appendChild​(org.w3c.dom.Node newChild)` |
    `java.lang.Object` | `clone()` | Clones this object (a deep cloning not including contents contained in Textual nodes).
    `int` | `coalesce​(boolean recursive)` | Coalesces children if they are siblings with the same type instances of Textual, Textual.isCoalesceable returns true.
    `java.util.List<Item>` | `detachChildren()` | Detaches all children and returns them in a list.
    `org.w3c.dom.NodeList` | `getChildNodes()` |
    `java.util.List<Item>` | `getChildren()` | Gets all children.
    `Element` | `getElement​(java.lang.String tname)` | Gets the first Element-type child with the tag name.
    `Element` | `getElement​(java.lang.String namespace, java.lang.String name, int mode)` | Gets the first Element-type child that matches the giving criteria.
    `int` | `getElementIndex​(int indexFrom, java.lang.String tname)` | Gets the index of the first Element-type child with the specified name.
    `int` | `getElementIndex​(int indexFrom, java.lang.String namespace, java.lang.String name, int mode)` | Gets the index of the Element-type first child that match the specified criteria.
    `java.util.Set<java.lang.String>` | `getElementNames()` | Returns a readonly set of names of element children.
    `java.util.List<Element>` | `getElements()` | Returns a cloned copy of all element children
    `java.util.List<Element>` | `getElements​(java.lang.String tname)` | Gets a readonly list of children with the tag name.
    `java.util.List<Element>` | `getElements​(java.lang.String namespace, java.lang.String name, int mode)` | Gets a readonly list of Element-type children that match the giving criteria.
    `java.lang.String` | `getElementValue​(java.lang.String tname, boolean trim)` | Gets the text of the first Element-type child with the tag name, with a trimming option.
    `java.lang.String` | `getElementValue​(java.lang.String namespace, java.lang.String name, int mode, boolean trim)` | Gets the value of the first Element-type child that matches the giving criteria, with a trimming option.
    `org.w3c.dom.Node` | `getFirstChild()` |
    `org.w3c.dom.Node` | `getLastChild()` |
    `boolean` | `hasChildNodes()` |
    `org.w3c.dom.Node` | `insertBefore​(org.w3c.dom.Node newChild, org.w3c.dom.Node refChild)` |
    `protected java.util.List<Item>` | `newChildren()` | Creates a list to hold child vertices.
    `org.w3c.dom.Node` | `removeChild​(org.w3c.dom.Node oldChild)` |
    `org.w3c.dom.Node` | `replaceChild​(org.w3c.dom.Node newChild, org.w3c.dom.Node oldChild)` |

    - ### Methods inherited from class org.zkoss.idom.impl.AbstractItem

      `cloneNode, compareDocumentPosition, detach, equals, getAttributes, getBaseURI, getDocument, getFeature, getLocalName, getLocator, getNamespaceURI, getNextSibling, getNodeName, getNodeValue, getOwnerDocument, getParent, getParentNode, getPrefix, getPreviousSibling, getText, getTextContent, getUserData, hasAttributes, hashCode, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, match, normalize, setLocator, setName, setNodeValue, setParent, setPrefix, setText, setTextContent, setUserData`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.zkoss.idom.Item

      `detach, getDocument, getLocator, getName, getParent, getText, setLocator, setName, setParent, setText`

    - ### Methods inherited from interface org.w3c.dom.Node

      `getNodeType`

- - ### Field Detail

    - #### _children

          protected java.util.List<Item> _children

      The list of the children. Never null.

  - ### Constructor Detail

    - #### AbstractGroup

          protected AbstractGroup()

      Constructor.

  - ### Method Detail

    - #### newChildren

          protected java.util.List<Item> newChildren()

      Creates a list to hold child vertices. Note: the list must be able to protect itself from adding unexpected child -- read-only, wrong type, undetached...

      The default implementation obeys the semantic of Element, i.e., it doesn't allow any child that cannot be a child of Element.

      For performance issue, we introduced a map to improve the search speed for Element node associated with a tag name.

    - #### getChildren

          public final java.util.List<Item> getChildren()

      Description copied from interface: `Group`
      Gets all children.

      The returned list is "live". Any modification to it affects the node. On the other hand, `Group.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.

      Specified by:
        `getChildren` in interface `Group`

    - #### detachChildren

          public final java.util.List<Item> detachChildren()

      Description copied from interface: `Group`
      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());`

      Specified by:
        `detachChildren` in interface `Group`

    - #### anyElement

          public final boolean anyElement()

    - #### getElementNames

          public final java.util.Set<java.lang.String> getElementNames()

      Description copied from interface: `Group`
      Returns a readonly set of names of element children. Then, you could use `Group.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 `Group.getChildren()` will affect it.

      Specified by:
        `getElementNames` in interface `Group`
      See Also:
        `Group.getElements()`

    - #### getElements

          public final java.util.List<Element> getElements()

      Description copied from interface: `Group`
      Returns a cloned copy of all element children

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

      Specified by:
        `getElements` in interface `Group`
      See Also:
        `Group.getElementNames()`

    - #### getElementIndex

          public final int getElementIndex​(int indexFrom,
                                           java.lang.String namespace,
                                           java.lang.String name,
                                           int mode)

      Description copied from interface: `Group`
      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.

      Specified by:
        `getElementIndex` in interface `Group`
      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

          public final int getElementIndex​(int indexFrom,
                                           java.lang.String tname)

      Description copied from interface: `Group`
      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"));

      Specified by:
        `getElementIndex` in interface `Group`
      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

    - #### getElement

          public final Element getElement​(java.lang.String namespace,
                                          java.lang.String name,
                                          int mode)

      Description copied from interface: `Group`
      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.

      Specified by:
        `getElement` in interface `Group`
      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

          public final Element getElement​(java.lang.String tname)

      Description copied from interface: `Group`
      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.

      Specified by:
        `getElement` in interface `Group`
      Parameters:
        `tname` - the tag name (i.e., Namespaceable.getName)
      Returns:
        the found element; null if not found or not supported

    - #### getElements

          public final java.util.List<Element> getElements​(java.lang.String namespace,
                                                           java.lang.String name,
                                                           int mode)

      Description copied from interface: `Group`
      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 `Group.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.

      Specified by:
        `getElements` in interface `Group`
      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

          public final java.util.List<Element> getElements​(java.lang.String tname)

      Description copied from interface: `Group`
      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 `Group.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.

      Specified by:
        `getElements` in interface `Group`
      Parameters:
        `tname` - the tag name (i.e., Namespaceable.getName)

    - #### getElementValue

          public final java.lang.String getElementValue​(java.lang.String namespace,
                                                        java.lang.String name,
                                                        int mode,
                                                        boolean trim)

      Description copied from interface: `Group`
      Gets the value of the first Element-type child that matches the giving criteria, with a trimming option.
      Specified by:
        `getElementValue` in interface `Group`
      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

          public final java.lang.String getElementValue​(java.lang.String tname,
                                                        boolean trim)

      Description copied from interface: `Group`
      Gets the text of the first Element-type child with the tag name, with a trimming option.
      Specified by:
        `getElementValue` in interface `Group`
      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

    - #### coalesce

          public final int coalesce​(boolean recursive)

      Description copied from interface: `Group`
      Coalesces children if they are siblings with the same type instances of Textual, Textual.isCoalesceable returns true.

      SAXBuilder.build will do the merging automatically.

      Specified by:
        `coalesce` in interface `Group`
      Parameters:
        `recursive` - true to coalesce all descendants; false to coalesce only the direct children

    - #### getChildNodes

          public final org.w3c.dom.NodeList getChildNodes()

      Specified by:
        `getChildNodes` in interface `org.w3c.dom.Node`
      Overrides:
        `getChildNodes` in class `AbstractItem`

    - #### getFirstChild

          public final org.w3c.dom.Node getFirstChild()

      Specified by:
        `getFirstChild` in interface `org.w3c.dom.Node`
      Overrides:
        `getFirstChild` in class `AbstractItem`

    - #### getLastChild

          public final org.w3c.dom.Node getLastChild()

      Specified by:
        `getLastChild` in interface `org.w3c.dom.Node`
      Overrides:
        `getLastChild` in class `AbstractItem`

    - #### hasChildNodes

          public final boolean hasChildNodes()

      Specified by:
        `hasChildNodes` in interface `org.w3c.dom.Node`
      Overrides:
        `hasChildNodes` in class `AbstractItem`

    - #### insertBefore

          public final org.w3c.dom.Node insertBefore​(org.w3c.dom.Node newChild,
                                                     org.w3c.dom.Node refChild)

      Specified by:
        `insertBefore` in interface `org.w3c.dom.Node`
      Overrides:
        `insertBefore` in class `AbstractItem`

    - #### replaceChild

          public final org.w3c.dom.Node replaceChild​(org.w3c.dom.Node newChild,
                                                     org.w3c.dom.Node oldChild)

      Specified by:
        `replaceChild` in interface `org.w3c.dom.Node`
      Overrides:
        `replaceChild` in class `AbstractItem`

    - #### removeChild

          public final org.w3c.dom.Node removeChild​(org.w3c.dom.Node oldChild)

      Specified by:
        `removeChild` in interface `org.w3c.dom.Node`
      Overrides:
        `removeChild` in class `AbstractItem`

    - #### appendChild

          public final org.w3c.dom.Node appendChild​(org.w3c.dom.Node newChild)

      Specified by:
        `appendChild` in interface `org.w3c.dom.Node`
      Overrides:
        `appendChild` in class `AbstractItem`

    - #### clone

          public java.lang.Object clone()

      Description copied from class: `AbstractItem`
      Clones this object (a deep cloning not including contents contained in Textual nodes). Note: after cloning, the read-only flag always becomes false, and the parent becomes null (i.e., detached).
      Specified by:
        `clone` in interface `Item`
      Overrides:
        `clone` in class `AbstractItem`