NodeCombiner (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2.tree, class: NodeCombiner

Package org.apache.commons.configuration2.tree

# Class NodeCombiner

java.lang.Object
org.apache.commons.configuration2.tree.NodeCombiner

Direct Known Subclasses:
  `MergeCombiner`, `OverrideCombiner`, `UnionCombiner`

public abstract class NodeCombiner extends Object

A base class for node combiner implementations.

A node combiner is an object that knows how two hierarchical node structures can be combined into a single one. Of course, there are many possible ways of implementing such a combination, for example constructing a union, an intersection, or an "override" structure (were nodes in the first hierarchy take precedence over nodes in the second hierarchy). This abstract base class only provides some helper methods and defines the common interface for node combiners. Concrete sub classes will implement the diverse combination algorithms.

For some concrete combiner implementations it is important to distinguish whether a node is a single node or whether it belongs to a list structure. Alone from the input structures, the combiner will not always be able to make this decision. So sometimes it may be necessary for the developer to configure the combiner and tell it, which nodes should be treated as list nodes. For this purpose the `addListNode()` method exists. It can be passed the name of a node, which should be considered a list node.

Since:
  1.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final NodeHandler<ImmutableNode>`
  `HANDLER`
  A default handler object for immutable nodes.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NodeCombiner()`
  Creates a new instance of `NodeCombiner`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListNode(String nodeName)`
  Adds the name of a node to the list of known list nodes.
  `abstract ImmutableNode`
  `combine(ImmutableNode node1, ImmutableNode node2)`
  Combines the hierarchies represented by the given root nodes.
  `Set<String>`
  `getListNodes()`
  Gets a set with the names of nodes that are known to be list nodes.
  `boolean`
  `isListNode(ImmutableNode node)`
  Checks if a node is a list node.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### HANDLER

    protected static final NodeHandler<ImmutableNode> HANDLER
    A default handler object for immutable nodes. This object can be used by derived classes for dealing with nodes. However, it provides only limited functionality; it supports only operations on child nodes, but no references to parent nodes.

- ## Constructor Details

  - ### NodeCombiner

    public NodeCombiner()
    Creates a new instance of `NodeCombiner`.

- ## Method Details

  - ### addListNode

    public void addListNode(String nodeName)
    Adds the name of a node to the list of known list nodes. This means that nodes with this name will never be combined.
    Parameters:
      `nodeName` - the name to be added

  - ### combine

    public abstract ImmutableNode combine(ImmutableNode node1, ImmutableNode node2)
    Combines the hierarchies represented by the given root nodes. This method must be defined in concrete sub classes with the implementation of a specific combination algorithm.
    Parameters:
      `node1` - the first root node
      `node2` - the second root node
    Returns:
      the root node of the resulting combined node structure

  - ### getListNodes

    public Set<String> getListNodes()
    Gets a set with the names of nodes that are known to be list nodes.
    Returns:
      a set with the names of list nodes

  - ### isListNode

    public boolean isListNode(ImmutableNode node)
    Checks if a node is a list node. This implementation tests if the given node name is contained in the set of known list nodes. Derived classes which use different criteria may overload this method.
    Parameters:
      `node` - the node to be tested
    Returns:
      a flag whether this is a list node