Interface XmlNode

@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

  • 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

    • namespaces

      @Nonnull default Map<String,String> namespaces()
      Returns the namespace context for this node — a map of namespace prefix to URI for all namespace bindings in scope, including those declared on this element and those inherited from ancestor elements.

      This is used by the write side to properly resolve prefixed attributes. For example, if an attribute mvn:combine.children exists on a child element but xmlns:mvn was declared on the root element, this map will contain the mvn → http://maven.apache.org/POM/4.0.0 binding.

      Returns:
      map of namespace prefix to URI, never null
      Since:
      4.1.0

    • 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.
      Use name() instead.

    • 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.
      Use namespaceUri() instead.

    • 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.
      Use prefix() instead.

    • 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.
      Use value() instead.

    • 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.
      Use attributes() instead.

    • 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.
      Use attribute(String) instead.

    • 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.
      Use children() instead.

    • 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.
      Use child(String) instead.

    • 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.
      Use inputLocation() instead.

    • 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) with an appropriate childMergeOverride value 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