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

Package org.apache.commons.configuration2.tree

# Class OverrideCombiner

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

public class OverrideCombiner extends NodeCombiner

A concrete combiner implementation that is able to construct an override combination.

An override combination means that nodes in the first node structure take precedence over nodes in the second, or - in other words - nodes of the second structure are only added to the resulting structure if they do not occur in the first one. This is especially suitable for dealing with the properties of configurations that are defined in an `override` section of a configuration definition file (hence the name).

This combiner will iterate over the second node hierarchy and find all nodes that are not contained in the first hierarchy; these are added to the result. If a node can be found in both structures, it is checked whether a combination (in a recursive way) can be constructed for the two, which will then be added. Per default, nodes are combined, which occur only once in both structures. This test is implemented in the `canCombine()` method.

As is true for the `UnionCombiner`, for this combiner list nodes are important. The `addListNode()` can be called to declare certain nodes as list nodes. This has the effect that these nodes will never be combined.

Since:
  1.3

- ## Field Summary

  ### Fields inherited from class org.apache.commons.configuration2.tree.NodeCombiner

  `HANDLER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OverrideCombiner()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addAttributes(ImmutableNode.Builder result, ImmutableNode node1, ImmutableNode node2)`
  Handles the attributes during a combination process.
  `protected ImmutableNode`
  `canCombine(ImmutableNode node1, ImmutableNode node2, ImmutableNode child)`
  Tests if a child node of the second node can be combined with the given child node of the first node.
  `ImmutableNode`
  `combine(ImmutableNode node1, ImmutableNode node2)`
  Constructs an override combination for the passed in node structures.

  ### Methods inherited from class org.apache.commons.configuration2.tree.NodeCombiner

  `addListNode, getListNodes, isListNode`

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

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

- ## Constructor Details

  - ### OverrideCombiner

    public OverrideCombiner()
    Constructs a new instance.

- ## Method Details

  - ### addAttributes

    protected void addAttributes(ImmutableNode.Builder result, ImmutableNode node1, ImmutableNode node2)
    Handles the attributes during a combination process. First all attributes of the first node are added to the result. Then all attributes of the second node, which are not contained in the first node, are also added.
    Parameters:
      `result` - the resulting node
      `node1` - the first node
      `node2` - the second node

  - ### canCombine

    protected ImmutableNode canCombine(ImmutableNode node1, ImmutableNode node2, ImmutableNode child)
    Tests if a child node of the second node can be combined with the given child node of the first node. If this is the case, the corresponding node will be returned, otherwise null. This implementation checks whether the child node occurs only once in both hierarchies and is no known list node.
    Parameters:
      `node1` - the first node
      `node2` - the second node
      `child` - the child node (of the first node)
    Returns:
      a child of the second node, with which a combination is possible

  - ### combine

    public ImmutableNode combine(ImmutableNode node1, ImmutableNode node2)
    Constructs an override combination for the passed in node structures.
    Specified by:
      `combine` in class `NodeCombiner`
    Parameters:
      `node1` - the first node
      `node2` - the second node
    Returns:
      the resulting combined node structure