Package nu.xom

Class Element


  • public class Element
    extends ParentNode

    This class represents an XML element. Each element has the following properties:

    • Local name
    • Prefix (which may be null or the empty string)
    • Namespace URI (which may be null or the empty string)
    • A list of attributes
    • A list of namespace declarations for this element (not including those inherited from its parent)
    • A list of child nodes
    Version:
    1.2.10
    Author:
    Elliotte Rusty Harold
    • Constructor Summary

      Constructors 
      Constructor Description
      Element​(String name)
      Creates a new element in no namespace.
      Element​(String name, String uri)
      Creates a new element in a namespace.
      Element​(Element element)
      Creates a deep copy of an element.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addAttribute​(Attribute attribute)
      Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI.
      void addNamespaceDeclaration​(String prefix, String uri)
      Declares a namespace prefix.
      void appendChild​(String text)
      Converts a string to a text node and appends that node to the children of this node.
      Node copy()
      Creates a deep copy of this element with no parent, that can be added to this document or a different one.
      Attribute getAttribute​(int index)
      Selects an attribute by index.
      Attribute getAttribute​(String name)
      Returns the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name in no namespace.
      Attribute getAttribute​(String localName, String namespaceURI)
      Returns the attribute with the specified name and namespace URI, or null if this element does not have an attribute with that name in that namespace.
      int getAttributeCount()
      Returns the number of attributes of this Element, not counting namespace declarations.
      String getAttributeValue​(String name)
      Returns the value of the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name.
      String getAttributeValue​(String localName, String namespaceURI)
      Returns the value of the attribute with the specified name and namespace URI, or null if this element does not have such an attribute.
      String getBaseURI()
      Returns the absolute base URI against which relative URIs in this element should be resolved.
      Elements getChildElements()
      Returns a list of all the child elements of this element in document order.
      Elements getChildElements​(String name)
      Returns a list of the child elements of this element with the specified name in no namespace.
      Elements getChildElements​(String localName, String namespaceURI)
      Returns a list of the immediate child elements of this element with the specified local name and namespace URI.
      Element getFirstChildElement​(String name)
      Returns the first child element with the specified name in no namespace.
      Element getFirstChildElement​(String localName, String namespaceURI)
      Returns the first child element with the specified local name and namespace URI.
      String getLocalName()
      Returns the local name of this element, not including the namespace prefix or colon.
      int getNamespaceDeclarationCount()
      Returns the number of namespace declarations on this element.
      String getNamespacePrefix()
      Returns the prefix of this element, or the empty string if this element does not have a prefix.
      String getNamespacePrefix​(int index)
      Returns the indexth namespace prefix declared on this element.
      String getNamespaceURI()
      Returns the namespace URI of this element, or the empty string if this element is not in a namespace.
      String getNamespaceURI​(String prefix)
      Returns the namespace URI mapped to the specified prefix within this element.
      String getQualifiedName()
      Returns the complete name of this element, including the namespace prefix if this element has one.
      String getValue()
      Returns the value of the element as defined by XPath 1.0.
      void insertChild​(String text, int position)
      Converts a string to a text node and inserts that node at the specified position.
      Attribute removeAttribute​(Attribute attribute)
      Removes an attribute from this element.
      Nodes removeChildren()
      Detaches all children from this node.
      void removeNamespaceDeclaration​(String prefix)
      Removes the mapping of the specified prefix.
      void setBaseURI​(String URI)
      Sets the URI from which this element was loaded, and against which relative URLs in this element will be resolved, unless an xml:base attribute overrides this.
      void setLocalName​(String localName)
      Sets the local name of this element.
      void setNamespacePrefix​(String prefix)
      Sets the namespace prefix of this element.
      void setNamespaceURI​(String uri)
      Sets the namespace URI of this element.
      protected Element shallowCopy()
      Creates a very shallow copy of the element with the same name and namespace URI, but no children, attributes, base URI, or namespace declaration.
      String toString()
      Returns a string representation of this element suitable for debugging and diagnosis.
      String toXML()
      Returns a string containing the XML serialization of this element.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • Element

        public Element​(String name)

        Creates a new element in no namespace.

        Parameters:
        name - the name of the element
        Throws:
        IllegalNameException - if name is not a legal XML 1.0 non-colonized name
      • Element

        public Element​(String name,
                       String uri)

        Creates a new element in a namespace.

        Parameters:
        name - the qualified name of the element
        uri - the namespace URI of the element
        Throws:
        IllegalNameException - if name is not a legal XML 1.0 name
        NamespaceConflictException - if name's prefix cannot be used with uri
        MalformedURIException - if uri is not an RFC 3986 absolute URI reference
      • Element

        public Element​(Element element)

        Creates a deep copy of an element. The copy is disconnected from the tree, and does not have a parent.

        Parameters:
        element - the element to copy
    • Method Detail

      • getChildElements

        public final Elements getChildElements​(String name)

        Returns a list of the child elements of this element with the specified name in no namespace. The elements returned are in document order.

        Parameters:
        name - the name of the elements included in the list
        Returns:
        a comatose list containing the child elements of this element with the specified name
      • getChildElements

        public final Elements getChildElements​(String localName,
                                               String namespaceURI)

        Returns a list of the immediate child elements of this element with the specified local name and namespace URI. Passing the empty string or null as the local name returns all elements in the specified namespace. Passing null or the empty string as the namespace URI returns elements with the specified name in no namespace. The elements returned are in document order.

        Parameters:
        localName - the name of the elements included in the list
        namespaceURI - the namespace URI of the elements included in the list
        Returns:
        a comatose list containing the child elements of this element with the specified name in the specified namespace
      • getChildElements

        public final Elements getChildElements()

        Returns a list of all the child elements of this element in document order.

        Returns:
        a comatose list containing all child elements of this element
      • getFirstChildElement

        public final Element getFirstChildElement​(String name)

        Returns the first child element with the specified name in no namespace. If there is no such element, it returns null.

        Parameters:
        name - the name of the element to return
        Returns:
        the first child element with the specified local name in no namespace or null if there is no such element
      • getFirstChildElement

        public final Element getFirstChildElement​(String localName,
                                                  String namespaceURI)

        Returns the first child element with the specified local name and namespace URI. If there is no such element, it returns null.

        Parameters:
        localName - the local name of the element to return
        namespaceURI - the namespace URI of the element to return
        Returns:
        the first child with the specified local name in the specified namespace, or null if there is no such element
      • addAttribute

        public void addAttribute​(Attribute attribute)

        Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI.

        Parameters:
        attribute - the attribute to add
        Throws:
        MultipleParentException - if the attribute is already attached to an element
        NamespaceConflictException - if the attribute's prefix is mapped to a different namespace URI than the same prefix is mapped to by this element, another attribute of this element, or an additional namespace declaration of this element
      • removeAttribute

        public Attribute removeAttribute​(Attribute attribute)

        Removes an attribute from this element.

        Parameters:
        attribute - the attribute to remove
        Returns:
        the attribute that was removed
        Throws:
        NoSuchAttributeException - if this element is not the parent of attribute
      • getAttribute

        public final Attribute getAttribute​(String name)

        Returns the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name in no namespace.

        Parameters:
        name - the name of the attribute
        Returns:
        the attribute of this element with the specified name
      • getAttribute

        public final Attribute getAttribute​(String localName,
                                            String namespaceURI)

        Returns the attribute with the specified name and namespace URI, or null if this element does not have an attribute with that name in that namespace.

        Parameters:
        localName - the local name of the attribute
        namespaceURI - the namespace of the attribute
        Returns:
        the attribute of this element with the specified name and namespace
      • getAttributeValue

        public final String getAttributeValue​(String name)

        Returns the value of the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name.

        Parameters:
        name - the name of the attribute
        Returns:
        the value of the attribute of this element with the specified name
      • getAttributeCount

        public final int getAttributeCount()

        Returns the number of attributes of this Element, not counting namespace declarations. This is always a non-negative number.

        Returns:
        the number of attributes in the container
      • getAttribute

        public final Attribute getAttribute​(int index)

        Selects an attribute by index. The index is purely for convenience and has no particular meaning. In particular, it is not necessarily the position of this attribute in the original document from which this Element object was read. As with most lists in Java, attributes are numbered from 0 to one less than the length of the list.

        In general, you should not add attributes to or remove attributes from the list while iterating across it. Doing so will change the indexes of the other attributes in the list. it is, however, safe to remove an attribute from either end of the list (0 or getAttributeCount()-1) until there are no attributes left.

        Parameters:
        index - the attribute to return
        Returns:
        the indexth attribute of this element
        Throws:
        IndexOutofBoundsException - if the index is negative or greater than or equal to the number of attributes of this element
      • getAttributeValue

        public final String getAttributeValue​(String localName,
                                              String namespaceURI)

        Returns the value of the attribute with the specified name and namespace URI, or null if this element does not have such an attribute.

        Parameters:
        localName - the name of the attribute
        namespaceURI - the namespace of the attribute
        Returns:
        the value of the attribute of this element with the specified name and namespace
      • getLocalName

        public final String getLocalName()

        Returns the local name of this element, not including the namespace prefix or colon.

        Returns:
        the local name of this element
      • getQualifiedName

        public final String getQualifiedName()

        Returns the complete name of this element, including the namespace prefix if this element has one.

        Returns:
        the qualified name of this element
      • getNamespacePrefix

        public final String getNamespacePrefix()

        Returns the prefix of this element, or the empty string if this element does not have a prefix.

        Returns:
        the prefix of this element
      • getNamespaceURI

        public final String getNamespaceURI()

        Returns the namespace URI of this element, or the empty string if this element is not in a namespace.

        Returns:
        the namespace URI of this element
      • getNamespaceURI

        public final String getNamespaceURI​(String prefix)

        Returns the namespace URI mapped to the specified prefix within this element. Returns null if this prefix is not associated with a URI.

        Parameters:
        prefix - the namespace prefix whose URI is desired
        Returns:
        the namespace URI mapped to prefix
      • setLocalName

        public void setLocalName​(String localName)

        Sets the local name of this element.

        Parameters:
        localName - the new local name
        Throws:
        IllegalNameException - if localName is not a legal, non-colonized name
      • setNamespaceURI

        public void setNamespaceURI​(String uri)

        Sets the namespace URI of this element.

        Parameters:
        uri - the new namespace URI
        Throws:
        MalformedURIException - if uri is not an absolute RFC 3986 URI reference
        NamespaceException - if this element has a prefix and uri is null or the empty string; or if the element's prefix is shared by an attribute or additional namespace
      • setNamespacePrefix

        public void setNamespacePrefix​(String prefix)

        Sets the namespace prefix of this element. You can pass null or the empty string to remove the prefix.

        Parameters:
        prefix - the new namespace prefix
        Throws:
        IllegalNameException - if prefix is not a legal XML non-colonized name
        NamespaceConflictException - if prefix is already in use by an attribute or additional namespace with a different URI than the element itself
      • insertChild

        public void insertChild​(String text,
                                int position)

        Converts a string to a text node and inserts that node at the specified position.

        Parameters:
        position - where to insert the child
        text - the string to convert to a text node and insert
        Throws:
        NullPointerException - if text is null
        IndexOutOfBoundsException - if the position is negative or greater than the number of children of the node
      • appendChild

        public void appendChild​(String text)

        Converts a string to a text node and appends that node to the children of this node.

        Parameters:
        text - String to add to this node
        Throws:
        IllegalAddException - if this node cannot have children of this type
        NullPointerException - if text is null
      • removeChildren

        public Nodes removeChildren()

        Detaches all children from this node.

        Subclassers should note that the default implementation of this method does not call removeChild or detach. If you override removeChild, you'll probably need to override this method as well.

        Returns:
        a list of all the children removed in the order they appeared in the element
      • addNamespaceDeclaration

        public void addNamespaceDeclaration​(String prefix,
                                            String uri)

        Declares a namespace prefix. This is only necessary when prefixes are used in element content and attribute values, as in XSLT and the W3C XML Schema Language. Do not use this method to declare prefixes for element and attribute names.

        You can supply an empty string for the prefix to declare a default namespace, provided the element itself has a prefix.

        If you do redeclare a prefix that is already used by an element or attribute name, the additional namespace is added if and only if the URI is the same. Conflicting namespace declarations will throw an exception.

        Parameters:
        prefix - the prefix to declare
        uri - the absolute URI reference to map the prefix to
        Throws:
        MalformedURIException - if URI is not an RFC 3986 URI reference
        IllegalNameException - if prefix is not a legal XML non-colonized name or the empty string
        NamespaceConflictException - if the mapping conflicts with an existing element, attribute, or additional namespace declaration
      • removeNamespaceDeclaration

        public void removeNamespaceDeclaration​(String prefix)

        Removes the mapping of the specified prefix. This method only removes additional namespaces added with addNamespaceDeclaration. It has no effect on namespaces of elements and attributes. If the prefix is not used on this element, this method does nothing.

        Parameters:
        prefix - the prefix whose declaration should be removed
      • getNamespaceDeclarationCount

        public final int getNamespaceDeclarationCount()

        Returns the number of namespace declarations on this element. This counts the namespace of the element itself (which may be the empty string), the namespace of each attribute, and each namespace added by addNamespaceDeclaration. However, prefixes used multiple times are only counted once; and the xml prefix used for xml:base, xml:lang, and xml:space is not counted even if one of these attributes is present on the element.

        The return value is almost always positive. It can be zero if and only if the element itself has the prefix xml; e.g. <xml:space />. This is not endorsed by the XML specification. The prefix xml is reserved for use by the W3C, which has only used it for attributes to date. You really shouldn't do this. Nonetheless, this is not malformed so XOM allows it.

        Returns:
        the number of namespaces declared by this element
      • getNamespacePrefix

        public final String getNamespacePrefix​(int index)

        Returns the indexth namespace prefix declared on this element. Namespaces inherited from ancestors are not included. The index is purely for convenience, and has no meaning in itself. This includes the namespaces of the element name and of all attributes' names (except for those with the prefix xml such as xml:space) as well as additional declarations made for attribute values and element content. However, prefixes used multiple times (e.g. on several attribute values) are only reported once. The default namespace is reported with an empty string prefix if present. Like most lists in Java, the first prefix is at index 0.

        If the namespaces on the element change for any reason (adding or removing an attribute in a namespace, adding or removing a namespace declaration, changing the prefix of an element, etc.) then this method may skip or repeat prefixes. Don't change the prefixes of an element while iterating across them.

        Parameters:
        index - the prefix to return
        Returns:
        the prefix
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than or equal to the number of namespaces declared by this element.
      • setBaseURI

        public void setBaseURI​(String URI)

        Sets the URI from which this element was loaded, and against which relative URLs in this element will be resolved, unless an xml:base attribute overrides this. Setting the base URI to null or the empty string removes any existing base URI.

        Specified by:
        setBaseURI in class ParentNode
        Parameters:
        URI - the new base URI for this element
        Throws:
        MalformedURIException - if URI is not a legal RFC 3986 absolute URI
      • getBaseURI

        public String getBaseURI()

        Returns the absolute base URI against which relative URIs in this element should be resolved. xml:base attributes in the same entity take precedence over the actual base URI of the document where the element was found or which was set by setBaseURI.

        This URI is made absolute before it is returned by resolving the information in this element against the information in its parent element and document entity. However, it is not always possible to fully absolutize the URI in all circumstances. In this case, this method returns the empty string to indicate the base URI of the current entity.

        If the element's xml:base attribute contains a value that is a syntactically illegal URI (e.g. %GF.html"), then the base URI is application dependent. XOM's choice is to behave as if the element did not have an xml:base attribute.

        Overrides:
        getBaseURI in class Node
        Returns:
        the base URI of this element
      • toXML

        public final String toXML()

        Returns a string containing the XML serialization of this element. This includes the element and all its attributes and descendants. However, it does not contain namespace declarations for namespaces inherited from ancestor elements.

        Specified by:
        toXML in class Node
        Returns:
        the XML representation of this element
      • getValue

        public final String getValue()

        Returns the value of the element as defined by XPath 1.0. This is the complete PCDATA content of the element, without any tags, comments, or processing instructions after all entity and character references have been resolved.

        Specified by:
        getValue in class Node
        Returns:
        XPath string value of this element
      • copy

        public Node copy()

        Creates a deep copy of this element with no parent, that can be added to this document or a different one.

        Subclassers should be wary. Implementing this method is trickier than it might seem, especially if you wish to avoid potential stack overflows in deep documents. In particular, you should not rely on the obvious recursive algorithm. Most subclasses should override the shallowCopy method instead.

        Specified by:
        copy in class Node
        Returns:
        a deep copy of this element with no parent
      • shallowCopy

        protected Element shallowCopy()

        Creates a very shallow copy of the element with the same name and namespace URI, but no children, attributes, base URI, or namespace declaration. This method is invoked as necessary by the copy method and the copy constructor.

        Subclasses should override this method so that it returns an instance of the subclass so that types are preserved when copying. This method should not add any attributes, namespace declarations, or children to the shallow copy. Any such items will be overwritten.

        Returns:
        an empty element with the same name and namespace as this element
      • toString

        public String toString()

        Returns a string representation of this element suitable for debugging and diagnosis. This is not the XML representation of the element.

        Overrides:
        toString in class Object
        Returns:
        a non-XML string representation of this element