org.zkoss.idom

Class Element

java.lang.Object

org.zkoss.idom.impl.AbstractItem

org.zkoss.idom.impl.AbstractGroup

org.zkoss.idom.Element

All Implemented Interfaces:

Serializable, Cloneable, Element, Node, Attributable, Group, Item, Namespaceable

public class Element
extends AbstractGroup
implements Attributable, Namespaceable, Element

The iDOM element.

Author:

tomyeh

See Also:

Attribute, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Element.AttrArray
protected class	Element.AttrMap

Nested classes/interfaces inherited from class org.zkoss.idom.impl.AbstractGroup

AbstractGroup.ChildArray, AbstractGroup.ElementMap

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<String,Namespace>	_addNamespaces Additional namespaces.
protected List<Attribute>	_attrs The attributes.
protected String	_lname The local name.
protected Namespace	_ns The namespace.

Fields inherited from class org.zkoss.idom.impl.AbstractGroup

_children

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

Fields inherited from interface org.zkoss.idom.Item

FIND_BY_PREFIX, FIND_BY_REGEX, FIND_BY_TAGNAME, FIND_IGNORE_CASE, FIND_RECURSIVE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Element() Constructor.
	Element(Namespace ns, String lname) Constructor.
	Element(String lname) Constructor without a namespace (i.e., Namespace.NO_NAMESPACE).
	Element(String nsURI, String tname) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	addDeclaredNamespace(Namespace ns) Adds a namespace to the namespace declaration.
Object	clone() Clones this object (a deep cloning not including contents contained in Textual nodes).
String	getAttribute(String tname)
int	getAttributeIndex(int indexFrom, String tname) Gets the index of the attribute with the giving local name.
int	getAttributeIndex(int indexFrom, String namespace, String name, int mode) Gets the index of the first attribute that matches the specified criteria.
Attribute	getAttributeItem(String tname) Gets the attribute with the tag name.
Attribute	getAttributeItem(String namespace, String name, int mode) Gets the first attribute that matches the specified criteria.
List<Attribute>	getAttributeItems() Returns all attributes of this object.
Attr	getAttributeNode(String tname)
Attr	getAttributeNodeNS(String nsURI, String lname)
String	getAttributeNS(String nsURI, String lname)
NamedNodeMap	getAttributes()
List<Attribute>	getAttributes(String namespace, String name, int mode) Gets a list of attributes of the specified criteria.
String	getAttributeValue(String tname) Returns the value of the attribute of the specified tag name, or null if not specified.
String	getAttributeValue(String namespace, String name, int mode) Gets the value of the first attribute that matches the giving criteria, or null if not found.
Object	getContent() Gets the content of this element.
Object	getContent(String path) Returns the content of the child element with the giving path, or null if the content is null or the child element doesn't exist.
Collection<Namespace>	getDeclaredNamespaces() Returns namespace declared on this element.
NodeList	getElementsByTagName(String tname)
NodeList	getElementsByTagNameNS(String nsURI, String lname)
String	getLocalName() Gets the local name of this item.
String	getName() Gets the tag name of the element -- the name with prefix.
Namespace	getNamespace() Gets the namespace.
Namespace	getNamespace(String prefix) Returns the Namespace in scope on this element for the given prefix (this involves searching up the tree, so the results depend on the current location of the element), or null if not found.
String	getNamespaceURI()
short	getNodeType()
String	getNodeValue() Always null.
String	getPrefix()
TypeInfo	getSchemaTypeInfo()
String	getTagName() Gets the tag name of this item.
String	getText() Returns the concatenation of Textual children; never null.
String	getText(boolean trim) Returns the concatenation of Textual children; never null.
boolean	hasAttribute(String tname)
boolean	hasAttributeNS(String nsURI, String lname)
boolean	hasAttributes()
boolean	hasContent(String path) Tests whether the child element with the giving path exists.
boolean	isRootElement() Tests whether this element is the root element of the owning document.
protected List<Attribute>	newAttrArray() Creates an empty list of attributes.
void	removeAttribute(String tname)
Attr	removeAttributeNode(Attr oldAttr)
void	removeAttributeNS(String nsURI, String lname)
Object	removeContent(String path) Removes the content of the child element with the giving path, and the child element itself if no other child.
Attribute	setAttribute(Attribute attr) Adds the giving attribute.
void	setAttribute(String tname, String value)
Attr	setAttributeNode(Attr newAttr)
Attr	setAttributeNodeNS(Attr newAttr)
void	setAttributeNS(String nsURI, String tname, String value)
Attribute	setAttributeValue(String tname, String value) Sets the value of the attribute with the giving tag name.
Object	setContent(Object obj) Sets the content of this element.
Object	setContent(String path, Object obj) Sets the content of the child element with the giving path.
void	setIdAttribute(String name, boolean isId)
void	setIdAttributeNode(Attr idAttr, boolean isId)
void	setIdAttributeNS(String namespaceURI, String localName, boolean isId)
void	setLocalName(String lname) Sets the local name of this item.
void	setName(String tname) Sets the tag name of the element.
void	setNamespace(Namespace ns) Sets the namespace.
void	setNamespace(String prefix, String nsURI) Sets the namespace.
void	setPrefix(String prefix)
void	setTagName(String tname) Sets the tag name of this item.
String	toString()

Methods inherited from class org.zkoss.idom.impl.AbstractGroup

anyElement, appendChild, coalesce, detachChildren, getChildNodes, getChildren, getElement, getElement, getElementIndex, getElementIndex, getElementNames, getElements, getElements, getElements, getElementValue, getElementValue, getFirstChild, getLastChild, hasChildNodes, insertBefore, newChildren, removeChild, replaceChild

Methods inherited from class org.zkoss.idom.impl.AbstractItem

cloneNode, compareDocumentPosition, detach, equals, getBaseURI, getDocument, getFeature, getLocator, getNextSibling, getNodeName, getOwnerDocument, getParent, getParentNode, getPreviousSibling, getTextContent, getUserData, hashCode, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, match, normalize, setLocator, setNodeValue, setParent, setText, setTextContent, setUserData

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.w3c.dom.Node

appendChild, cloneNode, compareDocumentPosition, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getNextSibling, getNodeName, getOwnerDocument, getParentNode, getPreviousSibling, getTextContent, getUserData, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setTextContent, setUserData

Methods inherited from interface org.zkoss.idom.Item

detach, getDocument, getLocator, getParent, setLocator, setParent, setText

Field Detail

_ns

protected Namespace _ns

The namespace.

_lname

protected String _lname

The local name.

_attrs

protected List<Attribute> _attrs

The attributes. May be null.

_addNamespaces

protected Map<String,Namespace> _addNamespaces

Additional namespaces. May be null

Constructor Detail

Element

public Element(String nsURI,
               String tname)

Constructor.

Parameters:

nsURI - the namespace URI

tname - the tag name

Element

public Element(Namespace ns,
               String lname)

Constructor.

Parameters:

ns - the namespace; if null, the default namespace is assumed (not necessary Namespace.NO_NAMESPACE).

lname - the local name

Element

public Element(String lname)

Constructor without a namespace (i.e., Namespace.NO_NAMESPACE).

Parameters:

lname - the local name

Element

protected Element()

Constructor. Unlike other constructors, it doesn't set the modification flag.

Method Detail

isRootElement

public final boolean isRootElement()

Tests whether this element is the root element of the owning document.

Note: false is returned if it doesn't has any parent.

getNamespace

public final Namespace getNamespace(String prefix)

Returns the Namespace in scope on this element for the given prefix (this involves searching up the tree, so the results depend on the current location of the element), or null if not found.

If prefix is empty, it searches for the "default" namespace in scope. Thus, to search for attribute's namespace, caller have to skip this one and use NO_NAMESPACE. (due XML, an attribute without prefix is NO_NAMESPACE)

Parameters:

prefix - namespace prefix to look up; null for empty

getDeclaredNamespaces

public final Collection<Namespace> getDeclaredNamespaces()

Returns namespace declared on this element.

It is not a "live" representation. Also, it is read-only.

Note: Namespace.equals compares namespace's URI. However, the distinction here is the prefix, because it is mainly for getNamespace(prefix).

Returns:

the namespace declarations.

addDeclaredNamespace

public final boolean addDeclaredNamespace(Namespace ns)

Adds a namespace to the namespace declaration.

Returns:

true if the namespace is added

Throws:

DOMException - if the name space with the same prefix already exists but with different URI

getContent

public final Object getContent()

Gets the content of this element.

The content of an element is the first Binary or Text child of the element. Each element can has zero or one content.

Note: getText() returns the concatenation of all Text children, not just the first one.

Returns:

the content of this element; null if no such child

See Also:

getContent(String)

setContent

public final Object setContent(Object obj)

Sets the content of this element.

All existent Binary or Text children of this element are removed first. If the object is a String, a Text item is created to hold it. Otherwise, a Binary item is created to hold it.

Non-Binary/Text children are preserved.

If obj is a Item or an array/collection of Item, this method will add them as child vertices rather than being the content. Moreover, if the first item of the array/collection is Item, it is assumed to be all valid component to being has valid vertices. If not, an exception is thrown.

Thus, getContent might not return the object being set by setContent.

Parameters:

obj - the object to set; null is OK

Returns:

the previous content

See Also:

getContent()

getContent

public final Object getContent(String path)

Returns the content of the child element with the giving path, or null if the content is null or the child element doesn't exist.

Note that there might be more than one child with the same path in an iDOM tree; this method simply picks the first one that matches and returns its content. To access certain one, you might use [n] to [@attr = value] specify which one to access.

To know whether the child element exists or content is null, use hasContent(java.lang.String).

The content of an element is a special feature of iDOM. Like a Map, it is designed to let developers use names (in a path-like format) to access objects. See setContent(String, Object).

Like Unix path, the giving name could use '/' to concatenate a series of child elements.

An empty path denotes this element itself. Leading, ending and consecutive '/' will be ignored.

Example:
Object o = element.getContent("abc/def");
String s = Objects.toString(element.getContent("ab/cd"));
element.setContent("t:ab/cd/f:ef", new Integer(10));

TODO: support [n] and [@attr = value]

Parameters:

path - a path; e.g., "b", "a/b", "t:a/t:b"

See Also:

getContent()

hasContent

public final boolean hasContent(String path)

Tests whether the child element with the giving path exists. Note that there might be more than one child with the same path in an iDOM tree; this method simply tell you that "yes", at least on such path exist. To get the content, use getContent(String).

setContent

public final Object setContent(String path,
                               Object obj)

Sets the content of the child element with the giving path.

Note that there might be more than one child with the same path in an iDOM tree; this method simply pick one that matches and set its content (see setContent(Object)).

The content of an element is a special feature of iDOM. Like a Map, it is designed to let developers use names (in a path-like format) to access objects. See getContent(String).

Like Unix path, the giving name could use '/' to concatenate a series of child elements.

An empty path denotes this element itself. Leading, ending and consecutive '/' will be ignored.

If any element in the path is not found, it will be created automatically.

Parameters:

path - a path; e.g., "b", "a/b", "t:a/t:b"

obj - the object to set; null is acceptable

Returns:

the previous content

See Also:

setContent(Object), removeContent(java.lang.String), hasContent(java.lang.String)

removeContent

public final Object removeContent(String path)

Removes the content of the child element with the giving path, and the child element itself if no other child.

Unlike setContent(String, Object) with null, the child element identified by path will be detached if it has no other child (but the content). So does its parent excluding this element. Thus, removeContent(path) could undo setContent(path, v).

Returns:

the previous content

See Also:

setContent(String, Object)

setNamespace

public final void setNamespace(Namespace ns)

Sets the namespace. If ns is null, the default namespace is assumed (not necessary Namespace.NO_NAMESPACE.

According W3C/DOM, unlike element, an attribute doesn't allow a namespace that has an URI but without a prefix.

Specified by:

setNamespace in interface Namespaceable

setNamespace

public final void setNamespace(String prefix,
                               String nsURI)

Sets the namespace.

getNamespace

public final Namespace getNamespace()

Description copied from interface: Namespaceable

Gets the namespace.

Specified by:

getNamespace in interface Namespaceable

Returns:

the namespace; never null

getTagName

public final String getTagName()

Description copied from interface: Namespaceable

Gets the tag name of this item. The tag name is also called the fully qualified name -- the name with the namespace prefix, e.g., prefix:name.

To get the local name (the name without prefix), Namespaceable.getLocalName could be used.

Specified by:

getTagName in interface Element

Specified by:

getTagName in interface Namespaceable

setTagName

public final void setTagName(String tname)

Description copied from interface: Namespaceable

Sets the tag name of this item.

Specified by:

setTagName in interface Namespaceable

getLocalName

public final String getLocalName()

Description copied from interface: Namespaceable

Gets the local name of this item. The local name is the name without prefix.

To get the tag name (the name with prefix), Namespaceable.getTagName could be used.

Specified by:

getLocalName in interface Node

Specified by:

getLocalName in interface Namespaceable

Overrides:

getLocalName in class AbstractItem

setLocalName

public final void setLocalName(String lname)

Description copied from interface: Namespaceable

Sets the local name of this item.

Specified by:

setLocalName in interface Namespaceable

getName

public final String getName()

Gets the tag name of the element -- the name with prefix. To get the local name, use getLocalName.

Specified by:

getName in interface Item

See Also:

Namespaceable.getTagName()

setName

public final void setName(String tname)

Sets the tag name of the element. It will affect the local name and the namespace's prefix.

Specified by:

setName in interface Item

Overrides:

setName in class AbstractItem

See Also:

Namespaceable.setTagName(java.lang.String)

getText

public final String getText()

Returns the concatenation of Textual children; never null. Note: both <tag/> and <tag></tag> returns an empty string. To tell the difference, check the number of children.

Specified by:

getText in interface Item

Overrides:

getText in class AbstractItem

See Also:

getText(boolean)

getText

public final String getText(boolean trim)

Returns the concatenation of Textual children; never null.

Parameters:

trim - whether to trim before returning

See Also:

getText()

getAttributeItems

public final List<Attribute> getAttributeItems()

Description copied from interface: Attributable

Returns all attributes of this object.

The returned list is "live". Any modification to it affects the object that owns the attributes.

If the new added attribute has the same tag name as that of any existent attribute, DOMException is thrown. Thus, it is, sometimes, more convenient to ue setAttribute.

Naming reason: we don't call it getAttributes() to avoid the name conflict with Node.getAttributes().

Specified by:

getAttributeItems in interface Attributable

Returns:

an empty list if no attribute at all

newAttrArray

protected List<Attribute> newAttrArray()

Creates an empty list of attributes.

getAttributeIndex

public final int getAttributeIndex(int indexFrom,
                                   String namespace,
                                   String name,
                                   int mode)

Description copied from interface: Attributable

Gets the index of the first attribute that matches the specified criteria.

Specified by:

getAttributeIndex in interface Attributable

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

Returns:

the index if found; -1 if not found

getAttributeIndex

public final int getAttributeIndex(int indexFrom,
                                   String tname)

Description copied from interface: Attributable

Gets the index of the attribute with the giving local name.

Specified by:

getAttributeIndex in interface Attributable

Parameters:

indexFrom - the index to start searching from; 0 for beginning

tname - the tag name (i.e., Attribute.getName()) -- consists of the prefix and the local name

Returns:

the index if found; -1 if not found

getAttributeItem

public final Attribute getAttributeItem(String namespace,
                                        String name,
                                        int mode)

Description copied from interface: Attributable

Gets the first attribute that matches the specified criteria.

The name is a bit strange because we have to avoid name conflicts with org.w3c.dom.Node.

Specified by:

getAttributeItem in interface Attributable

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

Returns:

the index if found; -1 if not found

getAttributeItem

public final Attribute getAttributeItem(String tname)

Description copied from interface: Attributable

Gets the attribute with the tag name.

The name is a bit strange because we have to avoid name conflicts with org.w3c.dom.Node.

Specified by:

getAttributeItem in interface Attributable

Parameters:

tname - the tag name (i.e., Attribute.getName()) -- consists of the prefix and the local name

Returns:

null if not found

getAttributes

public final List<Attribute> getAttributes(String namespace,
                                           String name,
                                           int mode)

Description copied from interface: Attributable

Gets a list of attributes of the specified criteria.

Specified by:

getAttributes in interface Attributable

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

Returns:

null if not found

setAttribute

public final Attribute setAttribute(Attribute attr)

Description copied from interface: Attributable

Adds the giving attribute. If there is any existent one with the same tag name, it will be replaced. If not, the new attribute will be appended.

Specified by:

setAttribute in interface Attributable

Parameters:

attr - the new attribute to add

Returns:

the attribute being replaced; null if no one is replaced

getAttributeValue

public final String getAttributeValue(String namespace,
                                      String name,
                                      int mode)

Description copied from interface: Attributable

Gets the value of the first attribute that matches the giving criteria, or null if not found.

According to Section 3.3.3 of XML 1.0 spec, the value is normalized, including trimmed.

Specified by:

getAttributeValue in interface Attributable

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 attribute; null if not found

getAttributeValue

public final String getAttributeValue(String tname)

Description copied from interface: Attributable

Returns the value of the attribute of the specified tag name, or null if not specified.

Note: unlike W3C's getAttribute, which returns empty if not specified, this method returns null if not specified.

Specified by:

getAttributeValue in interface Attributable

setAttributeValue

public final Attribute setAttributeValue(String tname,
                                         String value)

Description copied from interface: Attributable

Sets the value of the attribute with the giving tag name. If the attribute doesn't exist, a new attribute will be created and added.

Note: it looks similar to Attribute(String, String), but this method requires the tag name.

Specified by:

setAttributeValue in interface Attributable

Parameters:

tname - the tag name (i.e., Attribute.getName)

value - the new value.

Returns:

the attribute being replaced; null if no one is replaced

clone

public 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 AbstractGroup

getNodeType

public final short getNodeType()

Specified by:

getNodeType in interface Node

getNodeValue

public final String getNodeValue()

Always null. Unlike other nodes, it is not the same as getText.

Specified by:

getNodeValue in interface Node

Overrides:

getNodeValue in class AbstractItem

getAttributes

public final NamedNodeMap getAttributes()

Specified by:

getAttributes in interface Node

Overrides:

getAttributes in class AbstractItem

hasAttributes

public final boolean hasAttributes()

Specified by:

hasAttributes in interface Node

Overrides:

hasAttributes in class AbstractItem

getNamespaceURI

public final String getNamespaceURI()

Specified by:

getNamespaceURI in interface Node

Overrides:

getNamespaceURI in class AbstractItem

getPrefix

public final String getPrefix()

Specified by:

getPrefix in interface Node

Overrides:

getPrefix in class AbstractItem

setPrefix

public final void setPrefix(String prefix)

Specified by:

setPrefix in interface Node

Overrides:

setPrefix in class AbstractItem

getElementsByTagName

public final NodeList getElementsByTagName(String tname)

Specified by:

getElementsByTagName in interface Element

getElementsByTagNameNS

public final NodeList getElementsByTagNameNS(String nsURI,
                                             String lname)

Specified by:

getElementsByTagNameNS in interface Element

getAttributeNode

public final Attr getAttributeNode(String tname)

Specified by:

getAttributeNode in interface Element

getAttributeNodeNS

public final Attr getAttributeNodeNS(String nsURI,
                                     String lname)

Specified by:

getAttributeNodeNS in interface Element

getAttribute

public final String getAttribute(String tname)

Specified by:

getAttribute in interface Element

getAttributeNS

public final String getAttributeNS(String nsURI,
                                   String lname)

Specified by:

getAttributeNS in interface Element

setAttribute

public final void setAttribute(String tname,
                               String value)

Specified by:

setAttribute in interface Element

setAttributeNS

public final void setAttributeNS(String nsURI,
                                 String tname,
                                 String value)

Specified by:

setAttributeNS in interface Element

setAttributeNode

public final Attr setAttributeNode(Attr newAttr)

Specified by:

setAttributeNode in interface Element

setAttributeNodeNS

public final Attr setAttributeNodeNS(Attr newAttr)

Specified by:

setAttributeNodeNS in interface Element

removeAttribute

public final void removeAttribute(String tname)

Specified by:

removeAttribute in interface Element

removeAttributeNS

public final void removeAttributeNS(String nsURI,
                                    String lname)

Specified by:

removeAttributeNS in interface Element

removeAttributeNode

public final Attr removeAttributeNode(Attr oldAttr)

Specified by:

removeAttributeNode in interface Element

hasAttribute

public final boolean hasAttribute(String tname)

Specified by:

hasAttribute in interface Element

hasAttributeNS

public final boolean hasAttributeNS(String nsURI,
                                    String lname)

Specified by:

hasAttributeNS in interface Element

toString

public final String toString()

Overrides:

toString in class Object

getSchemaTypeInfo

public TypeInfo getSchemaTypeInfo()

Specified by:

getSchemaTypeInfo in interface Element

setIdAttribute

public void setIdAttribute(String name,
                           boolean isId)
                    throws DOMException

Specified by:

setIdAttribute in interface Element

Throws:

DOMException

setIdAttributeNS

public void setIdAttributeNS(String namespaceURI,
                             String localName,
                             boolean isId)
                      throws DOMException

Specified by:

setIdAttributeNS in interface Element

Throws:

DOMException

setIdAttributeNode

public void setIdAttributeNode(Attr idAttr,
                               boolean isId)
                        throws DOMException

Specified by:

setIdAttributeNode in interface Element

Throws:

DOMException