Package org.zkoss.idom

Class Element

    • Field Detail

      • _ns

        protected Namespace _ns
        The namespace.

      • _lname

        protected java.lang.String _lname
        The local name.

      • _attrs

        protected java.util.List<Attribute> _attrs
        The attributes. May be null.

      • _addNamespaces

        protected java.util.Map<java.lang.String,​Namespace> _addNamespaces
        Additional namespaces. May be null

    • Constructor Detail

      • Element

        public Element​(java.lang.String nsURI,
               java.lang.String tname)
        Constructor.
        Parameters:
        nsURI - the namespace URI
        tname - the tag name

      • Element

        public Element​(Namespace ns,
               java.lang.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​(java.lang.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​(java.lang.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 java.util.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 java.lang.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 java.lang.Object setContent​(java.lang.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 java.lang.Object getContent​(java.lang.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​(java.lang.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 java.lang.Object setContent​(java.lang.String path,
                                         java.lang.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 java.lang.Object removeContent​(java.lang.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​(java.lang.String prefix,
                               java.lang.String nsURI)
        Sets the namespace.

      • getTagName

        public final java.lang.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 org.w3c.dom.Element
        Specified by:
        getTagName in interface Namespaceable

      • setTagName

        public final void setTagName​(java.lang.String tname)
        Description copied from interface: Namespaceable
        Sets the tag name of this item.
        Specified by:
        setTagName in interface Namespaceable

      • getLocalName

        public final java.lang.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 org.w3c.dom.Node
        Overrides:
        getLocalName in class AbstractItem

      • setLocalName

        public final void setLocalName​(java.lang.String lname)
        Description copied from interface: Namespaceable
        Sets the local name of this item.
        Specified by:
        setLocalName in interface Namespaceable

      • getName

        public final java.lang.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()

      • getText

        public final java.lang.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 java.lang.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 java.util.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 java.util.List<Attribute> newAttrArray()
        Creates an empty list of attributes.

      • getAttributeIndex

        public final int getAttributeIndex​(int indexFrom,
                                   java.lang.String namespace,
                                   java.lang.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,
                                   java.lang.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​(java.lang.String namespace,
                                        java.lang.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​(java.lang.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 java.util.List<Attribute> getAttributes​(java.lang.String namespace,
                                                     java.lang.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 java.lang.String getAttributeValue​(java.lang.String namespace,
                                                java.lang.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 java.lang.String getAttributeValue​(java.lang.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​(java.lang.String tname,
                                         java.lang.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 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 AbstractGroup

      • getNodeType

        public final short getNodeType()
        Specified by:
        getNodeType in interface org.w3c.dom.Node

      • getNodeValue

        public final java.lang.String getNodeValue()
        Always null. Unlike other nodes, it is not the same as getText.
        Specified by:
        getNodeValue in interface org.w3c.dom.Node
        Overrides:
        getNodeValue in class AbstractItem

      • getAttributes

        public final org.w3c.dom.NamedNodeMap getAttributes()
        Specified by:
        getAttributes in interface org.w3c.dom.Node
        Overrides:
        getAttributes in class AbstractItem

      • hasAttributes

        public final boolean hasAttributes()
        Specified by:
        hasAttributes in interface org.w3c.dom.Node
        Overrides:
        hasAttributes in class AbstractItem

      • getNamespaceURI

        public final java.lang.String getNamespaceURI()
        Specified by:
        getNamespaceURI in interface org.w3c.dom.Node
        Overrides:
        getNamespaceURI in class AbstractItem

      • getPrefix

        public final java.lang.String getPrefix()
        Specified by:
        getPrefix in interface org.w3c.dom.Node
        Overrides:
        getPrefix in class AbstractItem

      • setPrefix

        public final void setPrefix​(java.lang.String prefix)
        Specified by:
        setPrefix in interface org.w3c.dom.Node
        Overrides:
        setPrefix in class AbstractItem

      • getElementsByTagName

        public final org.w3c.dom.NodeList getElementsByTagName​(java.lang.String tname)
        Specified by:
        getElementsByTagName in interface org.w3c.dom.Element

      • getElementsByTagNameNS

        public final org.w3c.dom.NodeList getElementsByTagNameNS​(java.lang.String nsURI,
                                                         java.lang.String lname)
        Specified by:
        getElementsByTagNameNS in interface org.w3c.dom.Element

      • getAttributeNode

        public final org.w3c.dom.Attr getAttributeNode​(java.lang.String tname)
        Specified by:
        getAttributeNode in interface org.w3c.dom.Element

      • getAttributeNodeNS

        public final org.w3c.dom.Attr getAttributeNodeNS​(java.lang.String nsURI,
                                                 java.lang.String lname)
        Specified by:
        getAttributeNodeNS in interface org.w3c.dom.Element

      • getAttribute

        public final java.lang.String getAttribute​(java.lang.String tname)
        Specified by:
        getAttribute in interface org.w3c.dom.Element

      • getAttributeNS

        public final java.lang.String getAttributeNS​(java.lang.String nsURI,
                                             java.lang.String lname)
        Specified by:
        getAttributeNS in interface org.w3c.dom.Element

      • setAttribute

        public final void setAttribute​(java.lang.String tname,
                               java.lang.String value)
        Specified by:
        setAttribute in interface org.w3c.dom.Element

      • setAttributeNS

        public final void setAttributeNS​(java.lang.String nsURI,
                                 java.lang.String tname,
                                 java.lang.String value)
        Specified by:
        setAttributeNS in interface org.w3c.dom.Element

      • setAttributeNode

        public final org.w3c.dom.Attr setAttributeNode​(org.w3c.dom.Attr newAttr)
        Specified by:
        setAttributeNode in interface org.w3c.dom.Element

      • setAttributeNodeNS

        public final org.w3c.dom.Attr setAttributeNodeNS​(org.w3c.dom.Attr newAttr)
        Specified by:
        setAttributeNodeNS in interface org.w3c.dom.Element

      • removeAttribute

        public final void removeAttribute​(java.lang.String tname)
        Specified by:
        removeAttribute in interface org.w3c.dom.Element

      • removeAttributeNS

        public final void removeAttributeNS​(java.lang.String nsURI,
                                    java.lang.String lname)
        Specified by:
        removeAttributeNS in interface org.w3c.dom.Element

      • removeAttributeNode

        public final org.w3c.dom.Attr removeAttributeNode​(org.w3c.dom.Attr oldAttr)
        Specified by:
        removeAttributeNode in interface org.w3c.dom.Element

      • hasAttribute

        public final boolean hasAttribute​(java.lang.String tname)
        Specified by:
        hasAttribute in interface org.w3c.dom.Element

      • hasAttributeNS

        public final boolean hasAttributeNS​(java.lang.String nsURI,
                                    java.lang.String lname)
        Specified by:
        hasAttributeNS in interface org.w3c.dom.Element

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getSchemaTypeInfo

        public org.w3c.dom.TypeInfo getSchemaTypeInfo()
        Specified by:
        getSchemaTypeInfo in interface org.w3c.dom.Element

      • setIdAttribute

        public void setIdAttribute​(java.lang.String name,
                           boolean isId)
                    throws DOMException
        Specified by:
        setIdAttribute in interface org.w3c.dom.Element
        Throws:
        DOMException

      • setIdAttributeNS

        public void setIdAttributeNS​(java.lang.String namespaceURI,
                             java.lang.String localName,
                             boolean isId)
                      throws DOMException
        Specified by:
        setIdAttributeNS in interface org.w3c.dom.Element
        Throws:
        DOMException

      • setIdAttributeNode

        public void setIdAttributeNode​(org.w3c.dom.Attr idAttr,
                               boolean isId)
                        throws DOMException
        Specified by:
        setIdAttributeNode in interface org.w3c.dom.Element
        Throws:
        DOMException