Class XmlService

java.lang.Object

org.apache.maven.api.xml.XmlService

Direct Known Subclasses:

DefaultXmlService

public abstract class XmlService
extends Object

Comprehensive service interface for XML operations including node creation, merging, reading, and writing.

This class provides XML merging functionality for Maven's XML handling and specifies the combination modes that control how XML elements are merged.

The merger supports two main types of combinations:

• Children combination: Controls how child elements are combined
• Self combination: Controls how the element itself is combined

Children combination modes (specified by combine.children attribute):

• merge (default): Merges elements with matching names
• append: Adds elements as siblings

Self combination modes (specified by combine.self attribute):

• merge (default): Merges attributes and values
• override: Completely replaces the element
• remove: Removes the element

For complex XML structures, combining can also be done based on:

• ID: Using the combine.id attribute
• Keys: Using the combine.keys attribute with comma-separated key names

Since:

4.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	XmlService.InputLocationBuilder	Interface for building input locations during XML parsing.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CHILDREN_COMBINATION_APPEND	Value indicating children should be appended as siblings
static final String	CHILDREN_COMBINATION_MERGE	Value indicating children should be merged based on element names
static final String	CHILDREN_COMBINATION_MODE_ATTRIBUTE	Attribute name controlling how child elements are combined
static final String	DEFAULT_CHILDREN_COMBINATION_MODE	Default mode for combining children DOMs during merge.
static final String	DEFAULT_SELF_COMBINATION_MODE	Default mode for combining a DOM node during merge.
static final String	ID_COMBINATION_MODE_ATTRIBUTE	Attribute name for ID-based combination mode
static final String	KEYS_COMBINATION_MODE_ATTRIBUTE	Attribute name for key-based combination mode.
static final String	SELF_COMBINATION_MERGE	Value indicating the element should be merged
static final String	SELF_COMBINATION_MODE_ATTRIBUTE	Attribute name controlling how the element itself is combined
static final String	SELF_COMBINATION_OVERRIDE	Value indicating the element should be completely overridden
static final String	SELF_COMBINATION_REMOVE	Value indicating the element should be removed

Constructor Summary

Constructors

Constructor	Description
XmlService()

Method Summary

Modifier and Type	Method	Description
protected abstract XmlNode	doMerge(XmlNode dominant, XmlNode recessive, Boolean childMergeOverride)	Implementation method for merging two XML nodes.
protected abstract XmlNode	doRead(InputStream input, XmlService.InputLocationBuilder locationBuilder)	Implementation method for reading an XML node from an input stream.
protected abstract XmlNode	doRead(Reader reader, XmlService.InputLocationBuilder locationBuilder)	Implementation method for reading an XML node from a reader.
protected abstract XmlNode	doRead(XMLStreamReader reader, XmlService.InputLocationBuilder locationBuilder)	Implementation method for reading an XML node from an XMLStreamReader.
protected abstract void	doWrite(XmlNode node, Writer writer)	Implementation method for writing an XML node to a writer.
static XmlNode	merge(XmlNode dominant, XmlNode recessive)	Convenience method to merge two XML nodes using default settings.
static XmlNode	merge(XmlNode dominant, XmlNode recessive, Boolean childMergeOverride)	Merges two XML nodes.
static XmlNode	read(InputStream input, XmlService.InputLocationBuilder locationBuilder)	Reads an XML node from an input stream.
static XmlNode	read(Reader reader)	Reads an XML node from a reader.
static XmlNode	read(Reader reader, XmlService.InputLocationBuilder locationBuilder)	Reads an XML node from a reader.
static XmlNode	read(XMLStreamReader reader)	Reads an XML node from an XMLStreamReader.
static XmlNode	read(XMLStreamReader reader, XmlService.InputLocationBuilder locationBuilder)	Reads an XML node from an XMLStreamReader.
static void	write(XmlNode node, Writer writer)	Writes an XML node to a writer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CHILDREN_COMBINATION_MODE_ATTRIBUTE

public static final String CHILDREN_COMBINATION_MODE_ATTRIBUTE

Attribute name controlling how child elements are combined

See Also:

• Constant Field Values

CHILDREN_COMBINATION_MERGE

public static final String CHILDREN_COMBINATION_MERGE

Value indicating children should be merged based on element names

See Also:

• Constant Field Values

CHILDREN_COMBINATION_APPEND

public static final String CHILDREN_COMBINATION_APPEND

Value indicating children should be appended as siblings

See Also:

• Constant Field Values

DEFAULT_CHILDREN_COMBINATION_MODE

public static final String DEFAULT_CHILDREN_COMBINATION_MODE

Default mode for combining children DOMs during merge. When element names match, the process will try to merge the element data, rather than putting the dominant and recessive elements as siblings.

See Also:

• Constant Field Values

SELF_COMBINATION_MODE_ATTRIBUTE

public static final String SELF_COMBINATION_MODE_ATTRIBUTE

Attribute name controlling how the element itself is combined

See Also:

• Constant Field Values

SELF_COMBINATION_OVERRIDE

public static final String SELF_COMBINATION_OVERRIDE

Value indicating the element should be completely overridden

See Also:

• Constant Field Values

SELF_COMBINATION_MERGE

public static final String SELF_COMBINATION_MERGE

Value indicating the element should be merged

See Also:

• Constant Field Values

SELF_COMBINATION_REMOVE

public static final String SELF_COMBINATION_REMOVE

Value indicating the element should be removed

See Also:

• Constant Field Values

DEFAULT_SELF_COMBINATION_MODE

public static final String DEFAULT_SELF_COMBINATION_MODE

Default mode for combining a DOM node during merge. When element names match, the process will try to merge element attributes and values, rather than overriding the recessive element completely.

See Also:

• Constant Field Values

ID_COMBINATION_MODE_ATTRIBUTE

public static final String ID_COMBINATION_MODE_ATTRIBUTE

Attribute name for ID-based combination mode

See Also:

• Constant Field Values

KEYS_COMBINATION_MODE_ATTRIBUTE

public static final String KEYS_COMBINATION_MODE_ATTRIBUTE

Attribute name for key-based combination mode. Value should be a comma-separated list of attribute names.

See Also:

• Constant Field Values

Constructor Details

XmlService

public XmlService()

Method Details

merge

@Nullable
public static XmlNode merge(XmlNode dominant,
 XmlNode recessive)

Convenience method to merge two XML nodes using default settings.

merge

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

Merges two XML nodes.

read

@Nonnull
public static XmlNode read(InputStream input,
 @Nullable
 XmlService.InputLocationBuilder locationBuilder)
                    throws XMLStreamException

Reads an XML node from an input stream.

Throws:

XMLStreamException

read

@Nonnull
public static XmlNode read(Reader reader)
                    throws XMLStreamException

Reads an XML node from a reader.

Throws:

XMLStreamException

read

@Nonnull
public static XmlNode read(Reader reader,
 @Nullable
 XmlService.InputLocationBuilder locationBuilder)
                    throws XMLStreamException

Reads an XML node from a reader.

Throws:

XMLStreamException

read

@Nonnull
public static XmlNode read(XMLStreamReader reader)
                    throws XMLStreamException

Reads an XML node from an XMLStreamReader.

Throws:

XMLStreamException

read

@Nonnull
public static XmlNode read(XMLStreamReader reader,
 @Nullable
 XmlService.InputLocationBuilder locationBuilder)
                    throws XMLStreamException

Reads an XML node from an XMLStreamReader.

Throws:

XMLStreamException

write

public static void write(XmlNode node,
 Writer writer)
                  throws IOException

Writes an XML node to a writer.

Throws:

IOException

doRead

protected abstract XmlNode doRead(InputStream input,
 XmlService.InputLocationBuilder locationBuilder)
                           throws XMLStreamException

Implementation method for reading an XML node from an input stream.

Parameters:

input - the input stream to read from

locationBuilder - optional builder for creating input location objects

Returns:

the parsed XML node

Throws:

XMLStreamException - if there is an error parsing the XML

doRead

protected abstract XmlNode doRead(Reader reader,
 XmlService.InputLocationBuilder locationBuilder)
                           throws XMLStreamException

Implementation method for reading an XML node from a reader.

Parameters:

reader - the reader to read from

locationBuilder - optional builder for creating input location objects

Returns:

the parsed XML node

Throws:

XMLStreamException - if there is an error parsing the XML

doRead

protected abstract XmlNode doRead(XMLStreamReader reader,
 XmlService.InputLocationBuilder locationBuilder)
                           throws XMLStreamException

Implementation method for reading an XML node from an XMLStreamReader.

Parameters:

reader - the XML stream reader to read from

locationBuilder - optional builder for creating input location objects

Returns:

the parsed XML node

Throws:

XMLStreamException - if there is an error parsing the XML

doWrite

protected abstract void doWrite(XmlNode node,
 Writer writer)
                         throws IOException

Implementation method for writing an XML node to a writer.

Parameters:

node - the XML node to write

writer - the writer to write to

Throws:

IOException - if there is an error writing the XML

doMerge

protected abstract XmlNode doMerge(XmlNode dominant,
 XmlNode recessive,
 Boolean childMergeOverride)

Implementation method for merging two XML nodes.

Parameters:

dominant - the dominant (higher priority) XML node

recessive - the recessive (lower priority) XML node

childMergeOverride - optional override for the child merge mode

Returns:

the merged XML node, or null if both inputs are null