View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration.tree;
18  
19  import java.util.Iterator;
20  import java.util.LinkedList;
21  import java.util.List;
22  
23  /***
24   * <p>
25   * A specialized implementation of the <code>NodeCombiner</code> interface
26   * that constructs a union from two passed in node hierarchies.
27   * </p>
28   * <p>
29   * The given source hierarchies are traversed and their nodes are added to the
30   * resulting structure. Under some circumstances two nodes can be combined
31   * rather than adding both. This is the case if both nodes are single children
32   * (no lists) of their parents and do not have values. The corresponding check
33   * is implemented in the <code>findCombineNode()</code> method.
34   * </p>
35   * <p>
36   * Sometimes it is not possible for this combiner to detect whether two nodes
37   * can be combined or not. Consider the following two node hierarchies:
38   * </p>
39   * <p>
40   *
41   * <pre>
42   * Hierarchy 1:
43   *
44   * Database
45   *   +--Tables
46   *        +--Table
47   *             +--name [users]
48   *             +--fields
49   *                   +--field
50   *                   |    +--name [uid]
51   *                   +--field
52   *                   |    +--name [usrname]
53   *                     ...
54   * </pre>
55   *
56   * </p>
57   * <p>
58   *
59   * <pre>
60   * Hierarchy 2:
61   *
62   * Database
63   *   +--Tables
64   *        +--Table
65   *             +--name [documents]
66   *             +--fields
67   *                   +--field
68   *                   |    +--name [docid]
69   *                   +--field
70   *                   |    +--name [docname]
71   *                     ...
72   * </pre>
73   *
74   * </p>
75   * <p>
76   * Both hierarchies contain data about database tables. Each describes a single
77   * table. If these hierarchies are to be combined, the result should probably
78   * look like the following:
79   * <p>
80   *
81   * <pre>
82   * Database
83   *   +--Tables
84   *        +--Table
85   *        |    +--name [users]
86   *        |    +--fields
87   *        |          +--field
88   *        |          |    +--name [uid]
89   *        |            ...
90   *        +--Table
91   *             +--name [documents]
92   *             +--fields
93   *                   +--field
94   *                   |    +--name [docid]
95   *                     ...
96   * </pre>
97   *
98   * </p>
99   * <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://jakarta.apache.org/commons/configuration/team-list.html">Commons
115  * Configuration team</a>
116  * @version $Id: UnionCombiner.java 439648 2006-09-02 20:42:10Z oheger $
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 }