Open Source Repository

Home /commons-configuration/commons-configuration-1.7 | Repository Home


org/apache/commons/configuration/tree/UnionCombiner.java
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.configuration.tree;

import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;

/**
 <p>
 * A specialized implementation of the <code>NodeCombiner</code> interface
 * that constructs a union from two passed in node hierarchies.
 </p>
 <p>
 * 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()</code> method.
 </p>
 <p>
 * Sometimes it is not possible for this combiner to detect whether two nodes
 * can be combined or not. Consider the following two node hierarchies:
 </p>
 <p>
 *
 <pre>
 * Hierarchy 1:
 *
 * Database
 *   +--Tables
 *        +--Table
 *             +--name [users]
 *             +--fields
 *                   +--field
 *                   |    +--name [uid]
 *                   +--field
 *                   |    +--name [usrname]
 *                     ...
 </pre>
 *
 </p>
 <p>
 *
 <pre>
 * Hierarchy 2:
 *
 * Database
 *   +--Tables
 *        +--Table
 *             +--name [documents]
 *             +--fields
 *                   +--field
 *                   |    +--name [docid]
 *                   +--field
 *                   |    +--name [docname]
 *                     ...
 </pre>
 *
 </p>
 <p>
 * 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:
 <p>
 *
 <pre>
 * Database
 *   +--Tables
 *        +--Table
 *        |    +--name [users]
 *        |    +--fields
 *        |          +--field
 *        |          |    +--name [uid]
 *        |            ...
 *        +--Table
 *             +--name [documents]
 *             +--fields
 *                   +--field
 *                   |    +--name [docid]
 *                     ...
 </pre>
 *
 </p>
 <p>
 * i.e. the <code>Tables</code> nodes should be combined, while the
 <code>Table</code> nodes should both be added to the resulting tree. From
 * the combiner's point of view there is no difference between the
 <code>Tables</code> and the <code>Table</code> nodes in the source trees,
 * so the developer has to help out and give a hint that the <code>Table</code>
 * nodes belong to a list structure. This can be done using the
 <code>addListNode()</code> method; this method expects the name of a node,
 * which should be treated as a list node. So if
 <code>addListNode("Table");</code> was called, the combiner knows that it
 * must not combine the <code>Table</code> nodes, but add it both to the
 * resulting tree.
 </p>
 *
 @author <a
 * href="http://commons.apache.org/configuration/team-list.html">Commons
 * Configuration team</a>
 @version $Id: UnionCombiner.java 561230 2007-07-31 04:17:09Z rahul $
 @since 1.3
 */
public class UnionCombiner extends NodeCombiner
{
    /**
     * Combines the given nodes to a new union node.
     *
     @param node1 the first source node
     @param node2 the second source node
     @return the union node
     */
    public ConfigurationNode combine(ConfigurationNode node1,
            ConfigurationNode node2)
    {
        ViewNode result = createViewNode();
        result.setName(node1.getName());
        result.appendAttributes(node1);
        result.appendAttributes(node2);

        // Check if nodes can be combined
        List children2 = new LinkedList(node2.getChildren());
        for (Iterator it = node1.getChildren().iterator(); it.hasNext();)
        {
            ConfigurationNode child1 = (ConfigurationNodeit.next();
            ConfigurationNode child2 = findCombineNode(node1, node2, child1,
                    children2);
            if (child2 != null)
            {
                result.addChild(combine(child1, child2));
                children2.remove(child2);
            }
            else
            {
                result.addChild(child1);
            }
        }

        // Add remaining children of node 2
        for (Iterator it = children2.iterator(); it.hasNext();)
        {
            result.addChild((ConfigurationNodeit.next());
        }

        return result;
    }

    /**
     <p>
     * Tries to find a child node of the second source node, with whitch 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 corresponsing
     * 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:
     </p>
     <p>
     <ul>
     <li>In both the first and the second source node there is only one child
     * node with the given name (no list structures).</li>
     <li>The given name is not in the list of known list nodes, i.e. it was
     * not passed to the <code>addListNode()</code> method.</li>
     <li>None of these matching child nodes has a value.</li>
     </ul>
     </p>
     <p>
     * If all of these tests are successfull, the matching child node of the
     * second source node is returned. Otherwise the result is <b>null</b>.
     </p>
     *
     @param node1 the first source node
     @param node2 the second source node
     @param child the child node of the first source node to be checked
     @param children a list with all children of the second source node
     @return the matching child node of the second source node or <b>null</b>
     * if there is none
     */
    protected ConfigurationNode findCombineNode(ConfigurationNode node1,
            ConfigurationNode node2, ConfigurationNode child, List children)
    {
        if (child.getValue() == null && !isListNode(child)
                && node1.getChildrenCount(child.getName()) == 1
                && node2.getChildrenCount(child.getName()) == 1)
        {
            ConfigurationNode child2 = (ConfigurationNodenode2.getChildren(
                    child.getName()).iterator().next();
            if (child2.getValue() == null)
            {
                return child2;
            }
        }
        return null;
    }
}