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