Package 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:

  • Field Details

    • _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 Details

    • 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 Details

    • 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:

    • 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

      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:

    • 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:

    • 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:

    • 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 Namespaceable
      Specified by:
      getLocalName in interface Node
      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:

    • 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:

    • 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

      public final String getText(boolean trim)
      Returns the concatenation of Textual children; never null.
      Parameters:
      trim - whether to trim before returning
      See Also:

    • 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