Class XmlElement

  • All Implemented Interfaces:
    Bean, ImmutableBean

    public final class XmlElement
    extends java.lang.Object
    implements 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 Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)
      Checks if this element equals another.
      java.util.Optional<java.lang.String> findAttribute​(java.lang.String attrName)
      Finds an attribute by name, or empty if not found.
      java.util.Optional<XmlElement> findChild​(java.lang.String childName)
      Finds the child element with the specified name, or empty if not found, throwing an exception if more than one.
      java.lang.String getAttribute​(java.lang.String attrName)
      Gets an attribute by name, throwing an exception if not found.
      com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.String> getAttributes()
      Gets the attributes.
      XmlElement getChild​(int index)
      Gets a child element by index.
      XmlElement getChild​(java.lang.String childName)
      Gets the child element with the specified name, throwing an exception if not found or more than one.
      com.google.common.collect.ImmutableList<XmlElement> getChildren()
      Gets the child elements.
      com.google.common.collect.ImmutableList<XmlElement> getChildren​(java.lang.String childName)
      Gets the child elements matching the specified name.
      java.lang.String getContent()
      Gets the element content.
      java.lang.String getName()
      Gets the element name.
      boolean hasContent()
      Checks if the element has content.
      int hashCode()
      Returns a suitable hash code.
      MetaBean metaBean()  
      static XmlElement ofChildren​(java.lang.String name, java.util.List<XmlElement> children)
      Obtains an instance with children and no attributes.
      static XmlElement ofChildren​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> attributes, java.util.List<XmlElement> children)
      Obtains an instance with children and attributes.
      static XmlElement ofContent​(java.lang.String name, java.lang.String content)
      Obtains an instance with content and no attributes.
      static XmlElement ofContent​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.String> attributes, java.lang.String content)
      Obtains an instance with content and attributes.
      java.util.stream.Stream<XmlElement> streamChildren​(java.lang.String childName)
      Gets the child elements matching the specified name.
      java.lang.String toString()
      Returns a string summary of the element.
      • Methods inherited from class java.lang.Object

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

      • ofContent

        public static XmlElement ofContent​(java.lang.String name,
                                           java.lang.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​(java.lang.String name,
                                           java.util.Map<java.lang.String,​java.lang.String> attributes,
                                           java.lang.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​(java.lang.String name,
                                            java.util.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​(java.lang.String name,
                                            java.util.Map<java.lang.String,​java.lang.String> attributes,
                                            java.util.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 java.lang.String getName()
        Gets the element name.
        Returns:
        the name
      • getAttribute

        public java.lang.String getAttribute​(java.lang.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:
        java.lang.IllegalArgumentException - if the attribute name does not exist
      • findAttribute

        public java.util.Optional<java.lang.String> findAttribute​(java.lang.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 com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.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 java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is invalid
      • getChildren

        public com.google.common.collect.ImmutableList<XmlElement> getChildren()
        Gets the child elements.

        This returns all the children of this element.

        Returns:
        the children
      • getChild

        public XmlElement getChild​(java.lang.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:
        java.lang.IllegalArgumentException - if there is more than one match or no matches
      • findChild

        public java.util.Optional<XmlElement> findChild​(java.lang.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:
        java.lang.IllegalArgumentException - if there is more than one match
      • getChildren

        public com.google.common.collect.ImmutableList<XmlElement> getChildren​(java.lang.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 java.util.stream.Stream<XmlElement> streamChildren​(java.lang.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
      • equals

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

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

        Overrides:
        equals in class java.lang.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 java.lang.Object
        Returns:
        the hash code
      • toString

        public java.lang.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 java.lang.Object
        Returns:
        the string form