Class XmlElement

  • All Implemented Interfaces:
    org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class XmlElement
    extends Object
    implements org.joda.beans.ImmutableBean
    A single element in the tree structure of XML.

    This class is a minimal, lightweight representation of an element in the XML tree. The element has a name, attributes, and either content or children.

    Note that this representation does not express all XML features. No support is provided for processing instructions, comments or mixed content. In addition, it is not possible to determine the difference between empty content and no children.

    There is no explicit support for namespaces. When creating instances, the caller may choose to use a convention to represent namespaces. For example, element and attribute names may use prefixes or the standard QName format.

    • Method Detail

      • ofContent

        public static XmlElement ofContent​(String name,
                                           String content)
        Obtains an instance with content and no attributes.

        Returns an element representing XML with content, but no children.

        Parameters:
        name - the element name, not empty
        content - the content, empty if the element has no content
        Returns:
        the element
      • ofContent

        public static XmlElement ofContent​(String name,
                                           Map<String,​String> attributes,
                                           String content)
        Obtains an instance with content and attributes.

        Returns an element representing XML with content and attributes but no children.

        Parameters:
        name - the element name, not empty
        attributes - the attributes, empty if the element has no attributes
        content - the content, empty if the element has no content
        Returns:
        the element
      • ofChildren

        public static XmlElement ofChildren​(String name,
                                            List<XmlElement> children)
        Obtains an instance with children and no attributes.

        Returns an element representing XML with children, but no content.

        Parameters:
        name - the element name, not empty
        children - the children, empty if the element has no children
        Returns:
        the element
      • ofChildren

        public static XmlElement ofChildren​(String name,
                                            Map<String,​String> attributes,
                                            List<XmlElement> children)
        Obtains an instance with children and attributes.

        Returns an element representing XML with children and attributes, but no content.

        Parameters:
        name - the element name, not empty
        attributes - the attributes, empty if the element has no attributes
        children - the children, empty if the element has no children
        Returns:
        the element
      • getName

        public String getName()
        Gets the element name.
        Returns:
        the name
      • getAttribute

        public String getAttribute​(String attrName)
        Gets an attribute by name, throwing an exception if not found.

        This returns the value of the attribute with the specified name. An exception is thrown if the attribute does not exist.

        Parameters:
        attrName - the attribute name to find
        Returns:
        the attribute value
        Throws:
        IllegalArgumentException - if the attribute name does not exist
      • findAttribute

        public Optional<String> findAttribute​(String attrName)
        Finds an attribute by name, or empty if not found.

        This returns the value of the attribute with the specified name. If the attribute is not found, optional empty is returned.

        Parameters:
        attrName - the attribute name to find
        Returns:
        the attribute value, optional
      • getAttributes

        public ImmutableMap<String,​String> getAttributes()
        Gets the attributes.

        This returns all the attributes of this element.

        Returns:
        the attributes
      • hasContent

        public boolean hasContent()
        Checks if the element has content.

        Content exists if it is non-empty.

        Returns:
        the content
      • getContent

        public String getContent()
        Gets the element content.

        If this element has no content, the empty string is returned.

        Returns:
        the content
      • getChild

        public XmlElement getChild​(int index)
        Gets a child element by index.
        Parameters:
        index - the index to find
        Returns:
        the child
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • getChildren

        public ImmutableList<XmlElement> getChildren()
        Gets the child elements.

        This returns all the children of this element.

        Returns:
        the children
      • getChild

        public XmlElement getChild​(String childName)
        Gets the child element with the specified name, throwing an exception if not found or more than one.

        This returns the child element with the specified name. An exception is thrown if there is more than one matching child or the child does not exist.

        Parameters:
        childName - the name to match
        Returns:
        the child matching the name
        Throws:
        IllegalArgumentException - if there is more than one match or no matches
      • findChild

        public Optional<XmlElement> findChild​(String childName)
        Finds the child element with the specified name, or empty if not found, throwing an exception if more than one.

        This returns the child element with the specified name. If the element is not found, optional empty is returned.

        Parameters:
        childName - the name to match
        Returns:
        the child matching the name, optional
        Throws:
        IllegalArgumentException - if there is more than one match
      • getChildren

        public ImmutableList<XmlElement> getChildren​(String childName)
        Gets the child elements matching the specified name.

        This returns all the child elements with the specified name.

        Parameters:
        childName - the name to match
        Returns:
        the children matching the name
      • streamChildren

        public Stream<XmlElement> streamChildren​(String childName)
        Gets the child elements matching the specified name.

        This returns all the child elements with the specified name.

        Parameters:
        childName - the name to match
        Returns:
        the children matching the name
      • metaBean

        public org.joda.beans.MetaBean metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean
      • equals

        public boolean equals​(Object obj)
        Checks if this element equals another.

        This compares the entire state of the element, including all children.

        Overrides:
        equals in class Object
        Parameters:
        obj - the other element, null returns false
        Returns:
        true if equal
      • hashCode

        public int hashCode()
        Returns a suitable hash code.

        This includes the entire state of the element, including all children.

        Overrides:
        hashCode in class Object
        Returns:
        the hash code
      • toString

        public String toString()
        Returns a string summary of the element.

        The string form includes the attributes and content, but summarizes the child elements.

        Overrides:
        toString in class Object
        Returns:
        the string form