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

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	XmlNode.Builder	Builder class for creating XmlNode instances.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CHILDREN_COMBINATION_APPEND	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.CHILDREN_COMBINATION_APPEND instead.
static final String	CHILDREN_COMBINATION_MERGE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.CHILDREN_COMBINATION_MERGE instead.
static final String	CHILDREN_COMBINATION_MODE_ATTRIBUTE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.CHILDREN_COMBINATION_MODE_ATTRIBUTE instead.
static final String	DEFAULT_CHILDREN_COMBINATION_MODE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.DEFAULT_CHILDREN_COMBINATION_MODE instead.
static final String	DEFAULT_SELF_COMBINATION_MODE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.DEFAULT_SELF_COMBINATION_MODE instead.
static final String	ID_COMBINATION_MODE_ATTRIBUTE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.ID_COMBINATION_MODE_ATTRIBUTE instead.
static final String	KEYS_COMBINATION_MODE_ATTRIBUTE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.KEYS_COMBINATION_MODE_ATTRIBUTE instead.
static final String	SELF_COMBINATION_MERGE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.SELF_COMBINATION_MERGE instead.
static final String	SELF_COMBINATION_MODE_ATTRIBUTE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.SELF_COMBINATION_MODE_ATTRIBUTE instead.
static final String	SELF_COMBINATION_OVERRIDE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.SELF_COMBINATION_OVERRIDE instead.
static final String	SELF_COMBINATION_REMOVE	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.SELF_COMBINATION_REMOVE instead.

Method Summary

Modifier and Type	Method	Description
String	attribute(String name)	Returns the value of a specific attribute.
Map<String,String>	attributes()	Returns an immutable map of all attributes defined on this XML node.
XmlNode	child(String name)	Returns the first child node with the specified name.
List<XmlNode>	children()	Returns an immutable list of all child nodes.
default String	getAttribute(String name)	Deprecated, for removal: This API element is subject to removal in a future version. Use attribute(String) instead.
default Map<String,String>	getAttributes()	Deprecated, for removal: This API element is subject to removal in a future version. Use attributes() instead.
default XmlNode	getChild(String name)	Deprecated, for removal: This API element is subject to removal in a future version. Use child(String) instead.
default List<XmlNode>	getChildren()	Deprecated, for removal: This API element is subject to removal in a future version. Use children() instead.
default Object	getInputLocation()	Deprecated, for removal: This API element is subject to removal in a future version. Use inputLocation() instead.
default String	getName()	Deprecated, for removal: This API element is subject to removal in a future version. Use name() instead.
default String	getNamespaceUri()	Deprecated, for removal: This API element is subject to removal in a future version. Use namespaceUri() instead.
default String	getPrefix()	Deprecated, for removal: This API element is subject to removal in a future version. Use prefix() instead.
default String	getValue()	Deprecated, for removal: This API element is subject to removal in a future version. Use value() instead.
Object	inputLocation()	Returns the input location information for this node, if available.
default XmlNode	merge(XmlNode source)	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.merge(XmlNode, XmlNode, Boolean) instead.
default XmlNode	merge(XmlNode source, Boolean childMergeOverride)	Deprecated, for removal: This API element is subject to removal in a future version. Use XmlService.merge(XmlNode, XmlNode, Boolean) instead.
static XmlNode	merge(XmlNode dominant, 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.
static XmlNode	merge(XmlNode dominant, XmlNode recessive, Boolean childMergeOverride)
String	name()	Returns the local name of this XML node.
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.
String	namespaceUri()	Returns the namespace URI of this XML node.
static XmlNode.Builder	newBuilder()	Returns a new builder for creating XmlNode instances.
static XmlNode	newInstance(String name)	Creates a new XmlNode instance with the specified name.
static XmlNode	newInstance(String name, String value)	Creates a new XmlNode instance with the specified name and value.
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.
static XmlNode	newInstance(String name, List<XmlNode> children)	Creates a new XmlNode instance with the specified name and children.
String	prefix()	Returns the namespace prefix of this XML node.
String	value()	Returns the text content of this XML node.

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.

Use XmlService.CHILDREN_COMBINATION_MODE_ATTRIBUTE instead.

See Also:

• Constant Field Values

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.

Use XmlService.CHILDREN_COMBINATION_MERGE instead.

See Also:

• Constant Field Values

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.

Use XmlService.CHILDREN_COMBINATION_APPEND instead.

See Also:

• Constant Field Values

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.

Use XmlService.DEFAULT_CHILDREN_COMBINATION_MODE instead.

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:

• Constant Field Values

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.

Use XmlService.SELF_COMBINATION_MODE_ATTRIBUTE instead.

See Also:

• Constant Field Values

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.

Use XmlService.SELF_COMBINATION_OVERRIDE instead.

See Also:

• Constant Field Values

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.

Use XmlService.SELF_COMBINATION_MERGE instead.

See Also:

• Constant Field Values

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.

Use XmlService.SELF_COMBINATION_REMOVE instead.

See Also:

• Constant Field Values

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.

Use XmlService.ID_COMBINATION_MODE_ATTRIBUTE instead.

In case of complex XML structures, combining can be done based on id.

See Also:

• Constant Field Values

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.

Use XmlService.KEYS_COMBINATION_MODE_ATTRIBUTE instead.

In case of complex XML structures, combining can be done based on keys. This is a comma separated list of attribute names.

See Also:

• Constant Field Values

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.

Use XmlService.DEFAULT_SELF_COMBINATION_MODE instead.

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:

• Constant Field Values

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