org.zkoss.idom
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

Field Summary

Fields inherited from interface org.zkoss.idom.Item

FIND_BY_PREFIX, FIND_BY_REGEX, FIND_BY_TAGNAME, FIND_IGNORE_CASE, FIND_RECURSIVE

Method Summary

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 Unlike getChildren() and getElementNames(), the returned list is NOT a 'live-facade' of the real ones.
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.

Methods inherited from interface org.zkoss.idom.Item

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

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)

getElementNames

java.util.Set<java.lang.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()

getElements

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

getElementNames()