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

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

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

protected

AbstractGroup() Constructor.

Method Summary

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 Unlike Group.getChildren() and Group.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.
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 doen'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