    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.tree;
    018
    019import java.util.LinkedList;
    020import java.util.List;
    021
    022/**
    023 * <p>
    024 * A specialized implementation of the {@code NodeCombiner} interface
    025 * that constructs a union from two passed in node hierarchies.
    026 * </p>
    027 * <p>
    028 * The given source hierarchies are traversed, and their nodes are added to the
    029 * resulting structure. Under some circumstances two nodes can be combined
    030 * rather than adding both. This is the case if both nodes are single children
    031 * (no lists) of their parents and do not have values. The corresponding check
    032 * is implemented in the {@code findCombineNode()} method.
    033 * </p>
    034 * <p>
    035 * Sometimes it is not possible for this combiner to detect whether two nodes
    036 * can be combined or not. Consider the following two node hierarchies:
    037 * </p>
    038 *
    039 * <pre>
    040 * Hierarchy 1:
    041 *
    042 * Database
    043 *   +--Tables
    044 *        +--Table
    045 *             +--name [users]
    046 *             +--fields
    047 *                   +--field
    048 *                   |    +--name [uid]
    049 *                   +--field
    050 *                   |    +--name [usrname]
    051 *                     ...
    052 * </pre>
    053 *
    054 * <pre>
    055 * Hierarchy 2:
    056 *
    057 * Database
    058 *   +--Tables
    059 *        +--Table
    060 *             +--name [documents]
    061 *             +--fields
    062 *                   +--field
    063 *                   |    +--name [docid]
    064 *                   +--field
    065 *                   |    +--name [docname]
    066 *                     ...
    067 * </pre>
    068 *
    069 * <p>
    070 * Both hierarchies contain data about database tables. Each describes a single
    071 * table. If these hierarchies are to be combined, the result should probably
    072 * look like the following:
    073 * </p>
    074 *
    075 * <pre>
    076 * Database
    077 *   +--Tables
    078 *        +--Table
    079 *        |    +--name [users]
    080 *        |    +--fields
    081 *        |          +--field
    082 *        |          |    +--name [uid]
    083 *        |            ...
    084 *        +--Table
    085 *             +--name [documents]
    086 *             +--fields
    087 *                   +--field
    088 *                   |    +--name [docid]
    089 *                     ...
    090 * </pre>
    091 *
    092 * <p>
    093 * i.e. the {@code Tables} nodes should be combined, while the
    094 * {@code Table} nodes should both be added to the resulting tree. From
    095 * the combiner's point of view there is no difference between the
    096 * {@code Tables} and the {@code Table} nodes in the source trees,
    097 * so the developer has to help out and give a hint that the {@code Table}
    098 * nodes belong to a list structure. This can be done using the
    099 * {@code addListNode()} method; this method expects the name of a node,
    100 * which should be treated as a list node. So if
    101 * {@code addListNode("Table");} was called, the combiner knows that it
    102 * must not combine the {@code Table} nodes, but add it both to the
    103 * resulting tree.
    104 * </p>
    105 * <p>
    106 * Another limitation is the handling of attributes: Attributes can only
    107 * have a single value. So if two nodes are to be combined which both have
    108 * an attribute with the same name, it is not possible to construct a
    109 * proper union attribute. In this case, the attribute value from the
    110 * first node is used.
    111 * </p>
    112 *
    113 * @since 1.3
    114 */
    115public class UnionCombiner extends NodeCombiner
    116{
    117    /**
    118     * Combines the given nodes to a new union node.
    119     *
    120     * @param node1 the first source node
    121     * @param node2 the second source node
    122     * @return the union node
    123     */
    124    @Override
    125    public ImmutableNode combine(final ImmutableNode node1,
    126            final ImmutableNode node2)
    127    {
    128        final ImmutableNode.Builder result = new ImmutableNode.Builder();
    129        result.name(node1.getNodeName());
    130
    131        // attributes of the first node take precedence
    132        result.addAttributes(node2.getAttributes());
    133        result.addAttributes(node1.getAttributes());
    134
    135        // Check if nodes can be combined
    136        final List<ImmutableNode> children2 = new LinkedList<>(node2.getChildren());
    137        for (final ImmutableNode child1 : node1.getChildren())
    138        {
    139            final ImmutableNode child2 = findCombineNode(node1, node2, child1
    140            );
    141            if (child2 != null)
    142            {
    143                result.addChild(combine(child1, child2));
    144                children2.remove(child2);
    145            }
    146            else
    147            {
    148                result.addChild(child1);
    149            }
    150        }
    151
    152        // Add remaining children of node 2
    153        for (final ImmutableNode c : children2)
    154        {
    155            result.addChild(c);
    156        }
    157
    158        return result.create();
    159    }
    160
    161    /**
    162     * <p>
    163     * Tries to find a child node of the second source node, with which a child
    164     * of the first source node can be combined. During combining of the source
    165     * nodes an iteration over the first source node's children is performed.
    166     * For each child node it is checked whether a corresponding child node in
    167     * the second source node exists. If this is the case, these corresponding
    168     * child nodes are recursively combined and the result is added to the
    169     * combined node. This method implements the checks whether such a recursive
    170     * combination is possible. The actual implementation tests the following
    171     * conditions:
    172     * </p>
    173     * <ul>
    174     * <li>In both the first and the second source node there is only one child
    175     * node with the given name (no list structures).</li>
    176     * <li>The given name is not in the list of known list nodes, i.e. it was
    177     * not passed to the {@code addListNode()} method.</li>
    178     * <li>None of these matching child nodes has a value.</li>
    179     * </ul>
    180     * <p>
    181     * If all of these tests are successful, the matching child node of the
    182     * second source node is returned. Otherwise the result is <b>null</b>.
    183     * </p>
    184     *
    185     * @param node1 the first source node
    186     * @param node2 the second source node
    187     * @param child the child node of the first source node to be checked
    188     * @return the matching child node of the second source node or <b>null</b>
    189     * if there is none
    190     */
    191    protected ImmutableNode findCombineNode(final ImmutableNode node1,
    192            final ImmutableNode node2, final ImmutableNode child)
    193    {
    194        if (child.getValue() == null && !isListNode(child)
    195                && HANDLER.getChildrenCount(node1, child.getNodeName()) == 1
    196                && HANDLER.getChildrenCount(node2, child.getNodeName()) == 1)
    197        {
    198            final ImmutableNode child2 =
    199                    HANDLER.getChildren(node2, child.getNodeName()).get(0);
    200            if (child2.getValue() == null)
    201            {
    202                return child2;
    203            }
    204        }
    205        return null;
    206    }
    207}