org.zkoss.idom.impl
Class AbstractGroup

java.lang.Object
  extended by org.zkoss.idom.impl.AbstractItem
      extended by 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


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo