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

Package org.apache.commons.configuration2.tree

# Class UnionCombiner

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

public class UnionCombiner extends NodeCombiner

A specialized implementation of the `NodeCombiner` interface that constructs a union from two passed in node hierarchies.

The given source hierarchies are traversed, and their nodes are added to the resulting structure. Under some circumstances two nodes can be combined rather than adding both. This is the case if both nodes are single children (no lists) of their parents and do not have values. The corresponding check is implemented in the `findCombineNode()` method.

Sometimes it is not possible for this combiner to detect whether two nodes can be combined or not. Consider the following two node hierarchies:

     Hierarchy 1:

     Database
       +--Tables
            +--Table
                 +--name [users]
                 +--fields
                       +--field
                       |    +--name [uid]
                       +--field
                       |    +--name [usrname]
                         ...

     Hierarchy 2:

     Database
       +--Tables
            +--Table
                 +--name [documents]
                 +--fields
                       +--field
                       |    +--name [docid]
                       +--field
                       |    +--name [docname]
                         ...

Both hierarchies contain data about database tables. Each describes a single table. If these hierarchies are to be combined, the result should probably look like the following:

     Database
       +--Tables
            +--Table
            |    +--name [users]
            |    +--fields
            |          +--field
            |          |    +--name [uid]
            |            ...
            +--Table
                 +--name [documents]
                 +--fields
                       +--field
                       |    +--name [docid]
                         ...

i.e. the `Tables` nodes should be combined, while the `Table` nodes should both be added to the resulting tree. From the combiner's point of view there is no difference between the `Tables` and the `Table` nodes in the source trees, so the developer has to help out and give a hint that the `Table` nodes belong to a list structure. This can be done using the `addListNode()` method; this method expects the name of a node, which should be treated as a list node. So if `addListNode("Table");` was called, the combiner knows that it must not combine the `Table` nodes, but add it both to the resulting tree.

Another limitation is the handling of attributes: Attributes can only have a single value. So if two nodes are to be combined which both have an attribute with the same name, it is not possible to construct a proper union attribute. In this case, the attribute value from the first node is used.

Since:
  1.3

- ## Field Summary

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

  `HANDLER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UnionCombiner()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ImmutableNode`
  `combine(ImmutableNode node1, ImmutableNode node2)`
  Combines the given nodes to a new union node.
  `protected ImmutableNode`
  `findCombineNode(ImmutableNode node1, ImmutableNode node2, ImmutableNode child)`
  Tries to find a child node of the second source node, with which a child of the first source node can be combined.

  ### 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

  - ### UnionCombiner

    public UnionCombiner()

- ## Method Details

  - ### combine

    public ImmutableNode combine(ImmutableNode node1, ImmutableNode node2)
    Combines the given nodes to a new union node.
    Specified by:
      `combine` in class `NodeCombiner`
    Parameters:
      `node1` - the first source node
      `node2` - the second source node
    Returns:
      the union node

  - ### findCombineNode

    protected ImmutableNode findCombineNode(ImmutableNode node1, ImmutableNode node2, ImmutableNode child)

    Tries to find a child node of the second source node, with which a child of the first source node can be combined. During combining of the source nodes an iteration over the first source node's children is performed. For each child node it is checked whether a corresponding child node in the second source node exists. If this is the case, these corresponding child nodes are recursively combined and the result is added to the combined node. This method implements the checks whether such a recursive combination is possible. The actual implementation tests the following conditions:

    - In both the first and the second source node there is only one child node with the given name (no list structures).
    - The given name is not in the list of known list nodes, i.e. it was not passed to the `addListNode()` method.
    - None of these matching child nodes has a value.

    If all of these tests are successful, the matching child node of the second source node is returned. Otherwise the result is null.

    Parameters:
      `node1` - the first source node
      `node2` - the second source node
      `child` - the child node of the first source node to be checked
    Returns:
      the matching child node of the second source node or null if there is none