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 }