    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 that constructs a union from two passed in node
    025 * hierarchies.
    026 * </p>
    027 * <p>
    028 * The given source hierarchies are traversed, and their nodes are added to the resulting structure. Under some
    029 * circumstances two nodes can be combined rather than adding both. This is the case if both nodes are single children
    030 * (no lists) of their parents and do not have values. The corresponding check is implemented in the
    031 * {@code findCombineNode()} method.
    032 * </p>
    033 * <p>
    034 * Sometimes it is not possible for this combiner to detect whether two nodes can be combined or not. Consider the
    035 * following two node hierarchies:
    036 * </p>
    037 *
    038 * <pre>
    039 * Hierarchy 1:
    040 *
    041 * Database
    042 *   +--Tables
    043 *        +--Table
    044 *             +--name [users]
    045 *             +--fields
    046 *                   +--field
    047 *                   |    +--name [uid]
    048 *                   +--field
    049 *                   |    +--name [usrname]
    050 *                     ...
    051 * </pre>
    052 *
    053 * <pre>
    054 * Hierarchy 2:
    055 *
    056 * Database
    057 *   +--Tables
    058 *        +--Table
    059 *             +--name [documents]
    060 *             +--fields
    061 *                   +--field
    062 *                   |    +--name [docid]
    063 *                   +--field
    064 *                   |    +--name [docname]
    065 *                     ...
    066 * </pre>
    067 *
    068 * <p>
    069 * Both hierarchies contain data about database tables. Each describes a single table. If these hierarchies are to be
    070 * combined, the result should probably look like the following:
    071 * </p>
    072 *
    073 * <pre>
    074 * Database
    075 *   +--Tables
    076 *        +--Table
    077 *        |    +--name [users]
    078 *        |    +--fields
    079 *        |          +--field
    080 *        |          |    +--name [uid]
    081 *        |            ...
    082 *        +--Table
    083 *             +--name [documents]
    084 *             +--fields
    085 *                   +--field
    086 *                   |    +--name [docid]
    087 *                     ...
    088 * </pre>
    089 *
    090 * <p>
    091 * i.e. the {@code Tables} nodes should be combined, while the {@code Table} nodes should both be added to the resulting
    092 * tree. From the combiner's point of view there is no difference between the {@code Tables} and the {@code Table} nodes
    093 * in the source trees, so the developer has to help out and give a hint that the {@code Table} nodes belong to a list
    094 * structure. This can be done using the {@code addListNode()} method; this method expects the name of a node, which
    095 * should be treated as a list node. So if {@code addListNode("Table");} was called, the combiner knows that it must not
    096 * combine the {@code Table} nodes, but add it both to the resulting tree.
    097 * </p>
    098 * <p>
    099 * Another limitation is the handling of attributes: Attributes can only have a single value. So if two nodes are to be
    100 * combined which both have an attribute with the same name, it is not possible to construct a proper union attribute.
    101 * In this case, the attribute value from the first node is used.
    102 * </p>
    103 *
    104 * @since 1.3
    105 */
    106public class UnionCombiner extends NodeCombiner {
    107    /**
    108     * Combines the given nodes to a new union node.
    109     *
    110     * @param node1 the first source node
    111     * @param node2 the second source node
    112     * @return the union node
    113     */
    114    @Override
    115    public ImmutableNode combine(final ImmutableNode node1, final ImmutableNode node2) {
    116        final ImmutableNode.Builder result = new ImmutableNode.Builder();
    117        result.name(node1.getNodeName());
    118
    119        // attributes of the first node take precedence
    120        result.addAttributes(node2.getAttributes());
    121        result.addAttributes(node1.getAttributes());
    122
    123        // Check if nodes can be combined
    124        final List<ImmutableNode> children2 = new LinkedList<>(node2.getChildren());
    125        for (final ImmutableNode child1 : node1) {
    126            final ImmutableNode child2 = findCombineNode(node1, node2, child1);
    127            if (child2 != null) {
    128                result.addChild(combine(child1, child2));
    129                children2.remove(child2);
    130            } else {
    131                result.addChild(child1);
    132            }
    133        }
    134
    135        // Add remaining children of node 2
    136        for (final ImmutableNode c : children2) {
    137            result.addChild(c);
    138        }
    139
    140        return result.create();
    141    }
    142
    143    /**
    144     * <p>
    145     * Tries to find a child node of the second source node, with which a child of the first source node can be combined.
    146     * During combining of the source nodes an iteration over the first source node's children is performed. For each child
    147     * node it is checked whether a corresponding child node in the second source node exists. If this is the case, these
    148     * corresponding child nodes are recursively combined and the result is added to the combined node. This method
    149     * implements the checks whether such a recursive combination is possible. The actual implementation tests the following
    150     * conditions:
    151     * </p>
    152     * <ul>
    153     * <li>In both the first and the second source node there is only one child node with the given name (no list
    154     * structures).</li>
    155     * <li>The given name is not in the list of known list nodes, i.e. it was not passed to the {@code addListNode()}
    156     * method.</li>
    157     * <li>None of these matching child nodes has a value.</li>
    158     * </ul>
    159     * <p>
    160     * If all of these tests are successful, the matching child node of the second source node is returned. Otherwise the
    161     * result is <b>null</b>.
    162     * </p>
    163     *
    164     * @param node1 the first source node
    165     * @param node2 the second source node
    166     * @param child the child node of the first source node to be checked
    167     * @return the matching child node of the second source node or <b>null</b> if there is none
    168     */
    169    protected ImmutableNode findCombineNode(final ImmutableNode node1, final ImmutableNode node2, final ImmutableNode child) {
    170        if (child.getValue() == null && !isListNode(child) && HANDLER.getChildrenCount(node1, child.getNodeName()) == 1
    171            && HANDLER.getChildrenCount(node2, child.getNodeName()) == 1) {
    172            final ImmutableNode child2 = HANDLER.getChildren(node2, child.getNodeName()).get(0);
    173            if (child2.getValue() == null) {
    174                return child2;
    175            }
    176        }
    177        return null;
    178    }
    179}