Interface XmlNode

All Known Implementing Classes:
XmlNodeImpl
@Experimental @ThreadSafe @Immutable public interface XmlNode
An immutable XML node representation that provides a clean API for working with XML data structures. This interface represents a single node in an XML document tree, containing information about the node's name, value, attributes, and child nodes.

Example usage:

 XmlNode node = XmlNode.newBuilder()
     .name("configuration")
     .attribute("version", "1.0")
     .child(XmlNode.newInstance("property", "value"))
     .build();
Since:
4.0.0

  • Field Details

    • CHILDREN_COMBINATION_MODE_ATTRIBUTE

      @Deprecated(since="4.0.0", forRemoval=true) static final String CHILDREN_COMBINATION_MODE_ATTRIBUTE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • CHILDREN_COMBINATION_MERGE

      @Deprecated(since="4.0.0", forRemoval=true) static final String CHILDREN_COMBINATION_MERGE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • CHILDREN_COMBINATION_APPEND

      @Deprecated(since="4.0.0", forRemoval=true) static final String CHILDREN_COMBINATION_APPEND
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • DEFAULT_CHILDREN_COMBINATION_MODE

      @Deprecated(since="4.0.0", forRemoval=true) static final String DEFAULT_CHILDREN_COMBINATION_MODE
      Deprecated, for removal: This API element is subject to removal in a future version.
      This default mode for combining children DOMs during merge means that where element names match, the process will try to merge the element data, rather than putting the dominant and recessive elements (which share the same element name) as siblings in the resulting DOM.
      See Also:

    • SELF_COMBINATION_MODE_ATTRIBUTE

      @Deprecated(since="4.0.0", forRemoval=true) static final String SELF_COMBINATION_MODE_ATTRIBUTE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • SELF_COMBINATION_OVERRIDE

      @Deprecated(since="4.0.0", forRemoval=true) static final String SELF_COMBINATION_OVERRIDE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • SELF_COMBINATION_MERGE

      @Deprecated(since="4.0.0", forRemoval=true) static final String SELF_COMBINATION_MERGE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • SELF_COMBINATION_REMOVE

      @Deprecated(since="4.0.0", forRemoval=true) static final String SELF_COMBINATION_REMOVE
      Deprecated, for removal: This API element is subject to removal in a future version.
      See Also:

    • ID_COMBINATION_MODE_ATTRIBUTE

      @Deprecated(since="4.0.0", forRemoval=true) static final String ID_COMBINATION_MODE_ATTRIBUTE
      Deprecated, for removal: This API element is subject to removal in a future version.
      In case of complex XML structures, combining can be done based on id.
      See Also:

    • KEYS_COMBINATION_MODE_ATTRIBUTE

      @Deprecated(since="4.0.0", forRemoval=true) static final String KEYS_COMBINATION_MODE_ATTRIBUTE
      Deprecated, for removal: This API element is subject to removal in a future version.
      In case of complex XML structures, combining can be done based on keys. This is a comma separated list of attribute names.
      See Also:

    • DEFAULT_SELF_COMBINATION_MODE

      @Deprecated(since="4.0.0", forRemoval=true) static final String DEFAULT_SELF_COMBINATION_MODE
      Deprecated, for removal: This API element is subject to removal in a future version.
      This default mode for combining a DOM node during merge means that where element names match, the process will try to merge the element attributes and values, rather than overriding the recessive element completely with the dominant one. This means that wherever the dominant element doesn't provide the value or a particular attribute, that value or attribute will be set from the recessive DOM node.
      See Also:

  • Method Details

    • name

      @Nonnull String name()
      Returns the local name of this XML node.
      Returns:
      the node name, never null

    • namespaceUri

      @Nonnull String namespaceUri()
      Returns the namespace URI of this XML node.
      Returns:
      the namespace URI, never null (empty string if no namespace)

    • prefix

      @Nonnull String prefix()
      Returns the namespace prefix of this XML node.
      Returns:
      the namespace prefix, never null (empty string if no prefix)

    • value

      @Nullable String value()
      Returns the text content of this XML node.
      Returns:
      the node's text value, or null if none exists

    • attributes

      @Nonnull Map<String,String> attributes()
      Returns an immutable map of all attributes defined on this XML node.
      Returns:
      map of attribute names to values, never null

    • attribute

      @Nullable String attribute(@Nonnull String name)
      Returns the value of a specific attribute.
      Parameters:
      name - the name of the attribute to retrieve
      Returns:
      the attribute value, or null if the attribute doesn't exist
      Throws:
      NullPointerException - if name is null

    • children

      @Nonnull List<XmlNode> children()
      Returns an immutable list of all child nodes.
      Returns:
      list of child nodes, never null

    • child

      @Nullable XmlNode child(String name)
      Returns the first child node with the specified name.
      Parameters:
      name - the name of the child node to find
      Returns:
      the first matching child node, or null if none found

    • inputLocation

      @Nullable Object inputLocation()
      Returns the input location information for this node, if available. This can be useful for error reporting and debugging.
      Returns:
      the input location object, or null if not available

    • getName

      @Deprecated(since="4.0.0", forRemoval=true) @Nonnull default String getName()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getNamespaceUri

      @Deprecated(since="4.0.0", forRemoval=true) @Nonnull default String getNamespaceUri()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getPrefix

      @Deprecated(since="4.0.0", forRemoval=true) @Nonnull default String getPrefix()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getValue

      @Deprecated(since="4.0.0", forRemoval=true) @Nullable default String getValue()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getAttributes

      @Deprecated(since="4.0.0", forRemoval=true) @Nonnull default Map<String,String> getAttributes()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getAttribute

      @Deprecated(since="4.0.0", forRemoval=true) @Nullable default String getAttribute(@Nonnull String name)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getChildren

      @Deprecated(since="4.0.0", forRemoval=true) @Nonnull default List<XmlNode> getChildren()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getChild

      @Deprecated(since="4.0.0", forRemoval=true) @Nullable default XmlNode getChild(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getInputLocation

      @Deprecated(since="4.0.0", forRemoval=true) @Nullable default Object getInputLocation()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • merge

      @Deprecated(since="4.0.0", forRemoval=true) default XmlNode merge(@Nullable XmlNode source)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use XmlService.merge(XmlNode, XmlNode, Boolean) instead

    • merge

      @Deprecated(since="4.0.0", forRemoval=true) default XmlNode merge(@Nullable XmlNode source, @Nullable Boolean childMergeOverride)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use XmlService.merge(XmlNode, XmlNode, Boolean) instead

    • merge

      @Deprecated(since="4.0.0", forRemoval=true) @Nullable static XmlNode merge(@Nullable XmlNode dominant, @Nullable XmlNode recessive)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use XmlService.merge(XmlNode, XmlNode, Boolean) instead
      Merge recessive into dominant and return either dominant with merged information or a clone of recessive if dominant is null.
      Parameters:
      dominant - the node
      recessive - if null, nothing will happen
      Returns:
      the merged node

    • merge

      @Nullable static XmlNode merge(@Nullable XmlNode dominant, @Nullable XmlNode recessive, @Nullable Boolean childMergeOverride)

    • newInstance

      static XmlNode newInstance(String name)
      Creates a new XmlNode instance with the specified name.
      Parameters:
      name - the name for the new node
      Returns:
      a new XmlNode instance
      Throws:
      NullPointerException - if name is null

    • newInstance

      static XmlNode newInstance(String name, String value)
      Creates a new XmlNode instance with the specified name and value.
      Parameters:
      name - the name for the new node
      value - the value for the new node
      Returns:
      a new XmlNode instance
      Throws:
      NullPointerException - if name is null

    • newInstance

      static XmlNode newInstance(String name, List<XmlNode> children)
      Creates a new XmlNode instance with the specified name and children.
      Parameters:
      name - the name for the new node
      children - the list of child nodes
      Returns:
      a new XmlNode instance
      Throws:
      NullPointerException - if name is null

    • newInstance

      static XmlNode newInstance(String name, String value, Map<String,String> attrs, List<XmlNode> children, Object location)
      Creates a new XmlNode instance with all properties specified.
      Parameters:
      name - the name for the new node
      value - the value for the new node
      attrs - the attributes for the new node
      children - the list of child nodes
      location - the input location information
      Returns:
      a new XmlNode instance
      Throws:
      NullPointerException - if name is null

    • newBuilder

      static XmlNode.Builder newBuilder()
      Returns a new builder for creating XmlNode instances.
      Returns:
      a new Builder instance