Package org.zkoss.idom.impl

Class 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

    • 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()

      • 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