Interface Group

  • All Superinterfaces:
    java.lang.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:
    Item, Attributable, Namespaceable, Binable
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.
      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.
    • Method Detail

      • getChildren

        java.util.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

        java.util.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,
                            java.lang.String namespace,
                            java.lang.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,
                            java.lang.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

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

        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.
        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​(java.lang.String namespace,
                           java.lang.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​(java.lang.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

        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.

        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

        java.util.List<Element> getElements​(java.lang.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)