A specialized implementation of the {@code NodeCombiner} interfacethat 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 {@code 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 {@code Tables} nodes should be combined, while the{@code Table} nodes should both be added to the resulting tree. Fromthe combiner's point of view there is no difference between the {@code Tables} and the {@code Table} nodes in the source trees,so the developer has to help out and give a hint that the {@code Table}nodes belong to a list structure. This can be done using the {@code addListNode()} method; this method expects the name of a node,which should be treated as a list node. So if {@code addListNode("Table");} was called, the combiner knows that itmust not combine the {@code Table} nodes, but add it both to theresulting 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.
@version $Id: UnionCombiner.java 1624601 2014-09-12 18:04:36Z oheger $
@since 1.3