    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     */
    017    package org.apache.commons.configuration.tree;
    018
    019    import java.util.Iterator;
    020    import java.util.LinkedList;
    021    import java.util.List;
    022
    023    /**
    024     * <p>
    025     * A specialized implementation of the <code>NodeCombiner</code> interface
    026     * that constructs a union from two passed in node hierarchies.
    027     * </p>
    028     * <p>
    029     * The given source hierarchies are traversed and their nodes are added to the
    030     * resulting structure. Under some circumstances two nodes can be combined
    031     * rather than adding both. This is the case if both nodes are single children
    032     * (no lists) of their parents and do not have values. The corresponding check
    033     * is implemented in the <code>findCombineNode()</code> method.
    034     * </p>
    035     * <p>
    036     * Sometimes it is not possible for this combiner to detect whether two nodes
    037     * can be combined or not. Consider the following two node hierarchies:
    038     * </p>
    039     * <p>
    040     *
    041     * <pre>
    042     * Hierarchy 1:
    043     *
    044     * Database
    045     *   +--Tables
    046     *        +--Table
    047     *             +--name [users]
    048     *             +--fields
    049     *                   +--field
    050     *                   |    +--name [uid]
    051     *                   +--field
    052     *                   |    +--name [usrname]
    053     *                     ...
    054     * </pre>
    055     *
    056     * </p>
    057     * <p>
    058     *
    059     * <pre>
    060     * Hierarchy 2:
    061     *
    062     * Database
    063     *   +--Tables
    064     *        +--Table
    065     *             +--name [documents]
    066     *             +--fields
    067     *                   +--field
    068     *                   |    +--name [docid]
    069     *                   +--field
    070     *                   |    +--name [docname]
    071     *                     ...
    072     * </pre>
    073     *
    074     * </p>
    075     * <p>
    076     * Both hierarchies contain data about database tables. Each describes a single
    077     * table. If these hierarchies are to be combined, the result should probably
    078     * look like the following:
    079     * <p>
    080     *
    081     * <pre>
    082     * Database
    083     *   +--Tables
    084     *        +--Table
    085     *        |    +--name [users]
    086     *        |    +--fields
    087     *        |          +--field
    088     *        |          |    +--name [uid]
    089     *        |            ...
    090     *        +--Table
    091     *             +--name [documents]
    092     *             +--fields
    093     *                   +--field
    094     *                   |    +--name [docid]
    095     *                     ...
    096     * </pre>
    097     *
    098     * </p>
    099     * <p>
    100     * i.e. the <code>Tables</code> nodes should be combined, while the
    101     * <code>Table</code> nodes should both be added to the resulting tree. From
    102     * the combiner's point of view there is no difference between the
    103     * <code>Tables</code> and the <code>Table</code> nodes in the source trees,
    104     * so the developer has to help out and give a hint that the <code>Table</code>
    105     * nodes belong to a list structure. This can be done using the
    106     * <code>addListNode()</code> method; this method expects the name of a node,
    107     * which should be treated as a list node. So if
    108     * <code>addListNode("Table");</code> was called, the combiner knows that it
    109     * must not combine the <code>Table</code> nodes, but add it both to the
    110     * resulting tree.
    111     * </p>
    112     *
    113     * @author <a
    114     * href="http://commons.apache.org/configuration/team-list.html">Commons
    115     * Configuration team</a>
    116     * @version $Id: UnionCombiner.java 561230 2007-07-31 04:17:09Z rahul $
    117     * @since 1.3
    118     */
    119    public class UnionCombiner extends NodeCombiner
    120    {
    121        /**
    122         * Combines the given nodes to a new union node.
    123         *
    124         * @param node1 the first source node
    125         * @param node2 the second source node
    126         * @return the union node
    127         */
    128        public ConfigurationNode combine(ConfigurationNode node1,
    129                ConfigurationNode node2)
    130        {
    131            ViewNode result = createViewNode();
    132            result.setName(node1.getName());
    133            result.appendAttributes(node1);
    134            result.appendAttributes(node2);
    135
    136            // Check if nodes can be combined
    137            List children2 = new LinkedList(node2.getChildren());
    138            for (Iterator it = node1.getChildren().iterator(); it.hasNext();)
    139            {
    140                ConfigurationNode child1 = (ConfigurationNode) it.next();
    141                ConfigurationNode child2 = findCombineNode(node1, node2, child1,
    142                        children2);
    143                if (child2 != null)
    144                {
    145                    result.addChild(combine(child1, child2));
    146                    children2.remove(child2);
    147                }
    148                else
    149                {
    150                    result.addChild(child1);
    151                }
    152            }
    153
    154            // Add remaining children of node 2
    155            for (Iterator it = children2.iterator(); it.hasNext();)
    156            {
    157                result.addChild((ConfigurationNode) it.next());
    158            }
    159
    160            return result;
    161        }
    162
    163        /**
    164         * <p>
    165         * Tries to find a child node of the second source node, with whitch a child
    166         * of the first source node can be combined. During combining of the source
    167         * nodes an iteration over the first source node's children is performed.
    168         * For each child node it is checked whether a corresponding child node in
    169         * the second source node exists. If this is the case, these corresponsing
    170         * child nodes are recursively combined and the result is added to the
    171         * combined node. This method implements the checks whether such a recursive
    172         * combination is possible. The actual implementation tests the following
    173         * conditions:
    174         * </p>
    175         * <p>
    176         * <ul>
    177         * <li>In both the first and the second source node there is only one child
    178         * node with the given name (no list structures).</li>
    179         * <li>The given name is not in the list of known list nodes, i.e. it was
    180         * not passed to the <code>addListNode()</code> method.</li>
    181         * <li>None of these matching child nodes has a value.</li>
    182         * </ul>
    183         * </p>
    184         * <p>
    185         * If all of these tests are successfull, the matching child node of the
    186         * second source node is returned. Otherwise the result is <b>null</b>.
    187         * </p>
    188         *
    189         * @param node1 the first source node
    190         * @param node2 the second source node
    191         * @param child the child node of the first source node to be checked
    192         * @param children a list with all children of the second source node
    193         * @return the matching child node of the second source node or <b>null</b>
    194         * if there is none
    195         */
    196        protected ConfigurationNode findCombineNode(ConfigurationNode node1,
    197                ConfigurationNode node2, ConfigurationNode child, List children)
    198        {
    199            if (child.getValue() == null && !isListNode(child)
    200                    && node1.getChildrenCount(child.getName()) == 1
    201                    && node2.getChildrenCount(child.getName()) == 1)
    202            {
    203                ConfigurationNode child2 = (ConfigurationNode) node2.getChildren(
    204                        child.getName()).iterator().next();
    205                if (child2.getValue() == null)
    206                {
    207                    return child2;
    208                }
    209            }
    210            return null;
    211        }
    212    }