org.zkoss.idom.impl
Class AbstractItem

java.lang.Object
  org.zkoss.idom.impl.AbstractItem

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.w3c.dom.Node, Item

Direct Known Subclasses:

AbstractGroup, AbstractTextual, Attribute, DocType, ProcessingInstruction

public abstract class AbstractItem
extends java.lang.Object
implements Item, org.w3c.dom.Node, java.io.Serializable, java.lang.Cloneable

A semi-implemented item for leaf vertices. A leaf item is a item without any children. For cores having child cores, use Group.

Important methods that the deriving might want to override.

Item.getName

It must be overrided to provide a local name.

Item.setName

Overrid it if it allows to change the name. Default: throws an exception.

Item.getText

Override it if it has a text representation. Default: returns null.

Item.setText

Overrid it if it allows to change the text. Default: throws an exception.

Node.getNodeType

It must be overrided to provide the type.

Item.clone

Override it if any other members to handle specially. Note: by definition, we do deep clone only.

Object.toString

Override if you want a representation other than XMLOutputter does.

Author:

tomyeh

See Also:

Item, Serialized Form

Field Summary

protected boolean

_modified The modification flag.

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

AbstractItem() Constructor.

Method Summary

org.w3c.dom.Node	appendChild(org.w3c.dom.Node newChild)
protected void	checkWritable() Checks whether this item is writable (ie, isReady).
void	clearModified(boolean includingDescendant) Clears the modification flag of this item and all its children if includingDescendant is true.
java.lang.Object	clone() Clones this object (a deep cloning not including contents contained in Textual nodes).
Item	clone(boolean preserveModified) Clones this item.
org.w3c.dom.Node	cloneNode(boolean deep)
short	compareDocumentPosition(org.w3c.dom.Node other)
Item	detach() Detach this item from its parent.
boolean	equals(java.lang.Object o) Overriding this method is prohibited.
org.w3c.dom.NamedNodeMap	getAttributes()
java.lang.String	getBaseURI()
org.w3c.dom.NodeList	getChildNodes()
Document	getDocument() Gets the document that owns this item.
java.lang.Object	getFeature(java.lang.String feature, java.lang.String version)
org.w3c.dom.Node	getFirstChild()
org.w3c.dom.Node	getLastChild()
java.lang.String	getLocalName()
Locator	getLocator() Gets the locator of this item.
java.lang.String	getNamespaceURI()
org.w3c.dom.Node	getNextSibling()
java.lang.String	getNodeName()
java.lang.String	getNodeValue()
org.w3c.dom.Document	getOwnerDocument()
Group	getParent() Gets the parent item.
org.w3c.dom.Node	getParentNode()
java.lang.String	getPrefix()
org.w3c.dom.Node	getPreviousSibling()
java.lang.String	getText() Gets the text of this item, or null if it is neither Textual nor Element.
java.lang.String	getTextContent()
java.lang.Object	getUserData(java.lang.String key)
boolean	hasAttributes()
boolean	hasChildNodes()
int	hashCode() Overriding this method is prohibited.
org.w3c.dom.Node	insertBefore(org.w3c.dom.Node newChild, org.w3c.dom.Node refChild)
boolean	isDefaultNamespace(java.lang.String namespaceURI)
boolean	isEqualNode(org.w3c.dom.Node arg)
boolean	isModified() Tests whether this item (or any of its children) is modified, i.e., the modification flag is set.
boolean	isReadonly() Tests whether this item is read-only.
boolean	isSameNode(org.w3c.dom.Node other)
boolean	isSupported(java.lang.String feature, java.lang.String version)
java.lang.String	lookupNamespaceURI(java.lang.String prefix)
java.lang.String	lookupPrefix(java.lang.String namespaceURI)
protected static boolean	match(Namespaceable vtx, java.lang.String namespace, java.lang.String name, java.util.regex.Pattern ptn, int mode) Tests whether a namespaceable item matches the criteria.
void	normalize()
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)
void	setLocator(Locator loc) Sets the locator of this item.
void	setModified() Sets the modification flag.
void	setName(java.lang.String name) Sets the name of the item.
void	setNodeValue(java.lang.String nodeValue)
void	setParent(Group parent) Sets the parent item.
void	setPrefix(java.lang.String prefix)
void	setReadonly(boolean readonly) Sets the read-only flag of this item.
void	setText(java.lang.String text) Sets the text of this item.
void	setTextContent(java.lang.String textContent)
java.lang.Object	setUserData(java.lang.String key, java.lang.Object data, org.w3c.dom.UserDataHandler handler)

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.zkoss.idom.Item

getName

Methods inherited from interface org.w3c.dom.Node

getNodeType

Field Detail

_modified

protected transient boolean _modified

The modification flag.

Constructor Detail

AbstractItem

protected AbstractItem()

Constructor.

Method Detail

checkWritable

protected final void checkWritable()

Checks whether this item is writable (ie, isReady).

Throws:

DOMException - with NO_MODIFICATION_ALLOWED_ERR if not writable

match

protected static boolean match(Namespaceable vtx,
                               java.lang.String namespace,
                               java.lang.String name,
                               java.util.regex.Pattern ptn,
                               int mode)

Tests whether a namespaceable item matches the criteria. If mode don't contain FIND_BY_REGEX, ptn is ignored.

isReadonly

public boolean isReadonly()

Description copied from interface: Item

Tests whether this item is read-only. Note: A item is read-only if the read-only flag is set (Item.setReadonly(boolean)) or any of its ancestor is read-only (i.e., the read-only flag is set).

Specified by:

isReadonly in interface Item

setReadonly

public void setReadonly(boolean readonly)

Sets the read-only flag of this item. It causes this item and all its descendants read-only, see isReadonly().

Deriving class might restrict more conditions here.

Specified by:

setReadonly in interface Item

isModified

public boolean isModified()

Description copied from interface: Item

Tests whether this item (or any of its children) is modified, i.e., the modification flag is set.

IDOM is smart enough to set the modification flag only if it is really modified -- i.e., assigning a different value (not just calling any setter).

When an object is serialized, the modification flag is reset. Also, an object generated by Item.clone(boolean) with preservedModified==false has also no modification flag set.

Specified by:

isModified in interface Item

clearModified

public void clearModified(boolean includingDescendant)

Description copied from interface: Item

Clears the modification flag of this item and all its children if includingDescendant is true.

Unlike other methods, it doesn't affected by the read-only flag.

Specified by:

clearModified in interface Item

Parameters:

includingDescendant - whether to clear the modified flags of descendants

setModified

public void setModified()

Description copied from interface: Item

Sets the modification flag. Unlike Item.clearModified(boolean), it won't set children's modification flags, rather it sets its parent's modification flag.

The modifiaction flag is maintain automatically, so you rarely needs to call this method.

Unlike other methods, it doesn't affected by the read-only flag.

Specified by:

setModified in interface Item

setName

public void setName(java.lang.String name)

Description copied from interface: Item

Sets the name of the item. For vertices that support namespace (implements Namespaceable), it is the same as setTagName.

Specified by:

setName in interface Item

See Also:

Namespaceable.setTagName(java.lang.String)

getText

public java.lang.String getText()

Description copied from interface: Item

Gets the text of this item, or null if it is neither Textual nor Element. For Element, the text is the catenation of all its textual children, including Text, CDATA, and Binary.

Besides String-type value, some item, e.g., Binary, allows any type of objects. Caller could test whether a item implements the Binable interface, and use Binable.getValue instead. For binable vertices, getText is actually getValue().toString().

The returned value is neither trimmed nor normalized.

Specified by:

getText in interface Item

setText

public void setText(java.lang.String text)

Description copied from interface: Item

Sets the text of this item.

Specified by:

setText in interface Item

getDocument

public Document getDocument()

Description copied from interface: Item

Gets the document that owns this item. The owning document is the first document in its ancestor. For DOM, the document can only be the root, so the owning documents of vertices in a DOM tree are all the same.

Specified by:

getDocument in interface Item

detach

public Item detach()

Description copied from interface: Item

Detach this item from its parent.

Because each item can belong to at most one parent at a time, it is important to detach it first, before added to another tree -- even if it is the same tree/parent.

It has the similar effect as:
getParent().getChildren().remove(this).

Naming reason: we don't call this method as getChildren() to be compatible with the naming style of Attributable.attributes -- which is limited to org.w3c.dom.Attr.getAttributes. Also, it doesn't have the setter and it is "live", so it 'seem' better to call it getChildren().

Specified by:

detach in interface Item

Returns:

this item

clone

public Item clone(boolean preserveModified)

Description copied from interface: Item

Clones this item. Unlike other objects, it does a deep cloning. Also, the returned object is detached by default. The readonly flags are cleaned. If preserveModified is false, all modification flags of the returned object are cleaned, too.

Specified by:

clone in interface Item

getParent

public final Group getParent()

Description copied from interface: Item

Gets the parent item.

Specified by:

getParent in interface Item

setParent

public void setParent(Group parent)

Description copied from interface: Item

Sets the parent item.

DO NOT call this method. It is used internally. Instead, use detach or thru getChildren().

Specified by:

setParent in interface Item

getLocator

public final Locator getLocator()

Description copied from interface: Item

Gets the locator of this item.

Specified by:

getLocator in interface Item

Returns:

the locator; null if not available (default)

setLocator

public final void setLocator(Locator loc)

Description copied from interface: Item

Sets the locator of this item.

Unlike other methods, it won't change the modification flag.

Specified by:

setLocator in interface Item

Parameters:

loc - the locator; null if not available

getNodeName

public java.lang.String getNodeName()

Specified by:

getNodeName in interface org.w3c.dom.Node

getNodeValue

public java.lang.String getNodeValue()

Specified by:

getNodeValue in interface org.w3c.dom.Node

setNodeValue

public void setNodeValue(java.lang.String nodeValue)

Specified by:

setNodeValue in interface org.w3c.dom.Node

getOwnerDocument

public org.w3c.dom.Document getOwnerDocument()

Specified by:

getOwnerDocument in interface org.w3c.dom.Node

cloneNode

public final org.w3c.dom.Node cloneNode(boolean deep)

Specified by:

cloneNode in interface org.w3c.dom.Node

getParentNode

public final org.w3c.dom.Node getParentNode()

Specified by:

getParentNode in interface org.w3c.dom.Node

getPreviousSibling

public final org.w3c.dom.Node getPreviousSibling()

Specified by:

getPreviousSibling in interface org.w3c.dom.Node

getNextSibling

public final org.w3c.dom.Node getNextSibling()

Specified by:

getNextSibling in interface org.w3c.dom.Node

getChildNodes

public org.w3c.dom.NodeList getChildNodes()

Specified by:

getChildNodes in interface org.w3c.dom.Node

getFirstChild

public org.w3c.dom.Node getFirstChild()

Specified by:

getFirstChild in interface org.w3c.dom.Node

getLastChild

public org.w3c.dom.Node getLastChild()

Specified by:

getLastChild in interface org.w3c.dom.Node

hasChildNodes

public boolean hasChildNodes()

Specified by:

hasChildNodes in interface org.w3c.dom.Node

insertBefore

public org.w3c.dom.Node insertBefore(org.w3c.dom.Node newChild,
                                     org.w3c.dom.Node refChild)

Specified by:

insertBefore in interface org.w3c.dom.Node

replaceChild

public org.w3c.dom.Node replaceChild(org.w3c.dom.Node newChild,
                                     org.w3c.dom.Node oldChild)

Specified by:

replaceChild in interface org.w3c.dom.Node

removeChild

public org.w3c.dom.Node removeChild(org.w3c.dom.Node oldChild)

Specified by:

removeChild in interface org.w3c.dom.Node

appendChild

public org.w3c.dom.Node appendChild(org.w3c.dom.Node newChild)

Specified by:

appendChild in interface org.w3c.dom.Node

normalize

public final void normalize()

Specified by:

normalize in interface org.w3c.dom.Node

isSupported

public final boolean isSupported(java.lang.String feature,
                                 java.lang.String version)

Specified by:

isSupported in interface org.w3c.dom.Node

getNamespaceURI

public java.lang.String getNamespaceURI()

Specified by:

getNamespaceURI in interface org.w3c.dom.Node

getPrefix

public java.lang.String getPrefix()

Specified by:

getPrefix in interface org.w3c.dom.Node

getLocalName

public java.lang.String getLocalName()

Specified by:

getLocalName in interface org.w3c.dom.Node

setPrefix

public void setPrefix(java.lang.String prefix)

Specified by:

setPrefix in interface org.w3c.dom.Node

getAttributes

public org.w3c.dom.NamedNodeMap getAttributes()

Specified by:

getAttributes in interface org.w3c.dom.Node

hasAttributes

public boolean hasAttributes()

Specified by:

hasAttributes in interface org.w3c.dom.Node

getBaseURI

public java.lang.String getBaseURI()

Specified by:

getBaseURI in interface org.w3c.dom.Node

compareDocumentPosition

public short compareDocumentPosition(org.w3c.dom.Node other)
                              throws DOMException

Specified by:

compareDocumentPosition in interface org.w3c.dom.Node

Throws:

DOMException

getTextContent

public java.lang.String getTextContent()
                                throws DOMException

Specified by:

getTextContent in interface org.w3c.dom.Node

Throws:

DOMException

setTextContent

public void setTextContent(java.lang.String textContent)
                    throws DOMException

Specified by:

setTextContent in interface org.w3c.dom.Node

Throws:

DOMException

isSameNode

public boolean isSameNode(org.w3c.dom.Node other)

Specified by:

isSameNode in interface org.w3c.dom.Node

lookupPrefix

public java.lang.String lookupPrefix(java.lang.String namespaceURI)

Specified by:

lookupPrefix in interface org.w3c.dom.Node

isDefaultNamespace

public boolean isDefaultNamespace(java.lang.String namespaceURI)

Specified by:

isDefaultNamespace in interface org.w3c.dom.Node

lookupNamespaceURI

public java.lang.String lookupNamespaceURI(java.lang.String prefix)

Specified by:

lookupNamespaceURI in interface org.w3c.dom.Node

isEqualNode

public boolean isEqualNode(org.w3c.dom.Node arg)

Specified by:

isEqualNode in interface org.w3c.dom.Node

getFeature

public java.lang.Object getFeature(java.lang.String feature,
                                   java.lang.String version)

Specified by:

getFeature in interface org.w3c.dom.Node

setUserData

public java.lang.Object setUserData(java.lang.String key,
                                    java.lang.Object data,
                                    org.w3c.dom.UserDataHandler handler)

Specified by:

setUserData in interface org.w3c.dom.Node

getUserData

public java.lang.Object getUserData(java.lang.String key)

Specified by:

getUserData in interface org.w3c.dom.Node

equals

public final boolean equals(java.lang.Object o)

Overriding this method is prohibited.

Overrides:

equals in class java.lang.Object

hashCode

public final int hashCode()

Overriding this method is prohibited.

Overrides:

hashCode in class java.lang.Object

clone

public java.lang.Object clone()

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

Overrides:

clone in class java.lang.Object