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 * https://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.configuration2.tree;
18
19 import java.util.LinkedList;
20 import java.util.List;
21
22 /**
23 * <p>
24 * A specialized implementation of the {@code NodeCombiner} interface that constructs a union from two passed in node
25 * hierarchies.
26 * </p>
27 * <p>
28 * The given source hierarchies are traversed, and their nodes are added to the resulting structure. Under some
29 * circumstances two nodes can be combined rather than adding both. This is the case if both nodes are single children
30 * (no lists) of their parents and do not have values. The corresponding check is implemented in the
31 * {@code findCombineNode()} method.
32 * </p>
33 * <p>
34 * Sometimes it is not possible for this combiner to detect whether two nodes can be combined or not. Consider the
35 * following two node hierarchies:
36 * </p>
37 *
38 * <pre>
39 * Hierarchy 1:
40 *
41 * Database
42 * +--Tables
43 * +--Table
44 * +--name [users]
45 * +--fields
46 * +--field
47 * | +--name [uid]
48 * +--field
49 * | +--name [usrname]
50 * ...
51 * </pre>
52 *
53 * <pre>
54 * Hierarchy 2:
55 *
56 * Database
57 * +--Tables
58 * +--Table
59 * +--name [documents]
60 * +--fields
61 * +--field
62 * | +--name [docid]
63 * +--field
64 * | +--name [docname]
65 * ...
66 * </pre>
67 *
68 * <p>
69 * Both hierarchies contain data about database tables. Each describes a single table. If these hierarchies are to be
70 * combined, the result should probably look like the following:
71 * </p>
72 *
73 * <pre>
74 * Database
75 * +--Tables
76 * +--Table
77 * | +--name [users]
78 * | +--fields
79 * | +--field
80 * | | +--name [uid]
81 * | ...
82 * +--Table
83 * +--name [documents]
84 * +--fields
85 * +--field
86 * | +--name [docid]
87 * ...
88 * </pre>
89 *
90 * <p>
91 * i.e. the {@code Tables} nodes should be combined, while the {@code Table} nodes should both be added to the resulting
92 * tree. From the combiner's point of view there is no difference between the {@code Tables} and the {@code Table} nodes
93 * in the source trees, so the developer has to help out and give a hint that the {@code Table} nodes belong to a list
94 * structure. This can be done using the {@code addListNode()} method; this method expects the name of a node, which
95 * should be treated as a list node. So if {@code addListNode("Table");} was called, the combiner knows that it must not
96 * combine the {@code Table} nodes, but add it both to the resulting tree.
97 * </p>
98 * <p>
99 * Another limitation is the handling of attributes: Attributes can only have a single value. So if two nodes are to be
100 * combined which both have an attribute with the same name, it is not possible to construct a proper union attribute.
101 * In this case, the attribute value from the first node is used.
102 * </p>
103 *
104 * @since 1.3
105 */
106 public class UnionCombiner extends NodeCombiner {
107
108 /**
109 * Combines the given nodes to a new union node.
110 *
111 * @param node1 the first source node
112 * @param node2 the second source node
113 * @return the union node
114 */
115 @Override
116 public ImmutableNode combine(final ImmutableNode node1, final ImmutableNode node2) {
117 final ImmutableNode.Builder result = new ImmutableNode.Builder();
118 result.name(node1.getNodeName());
119
120 // attributes of the first node take precedence
121 result.addAttributes(node2.getAttributes());
122 result.addAttributes(node1.getAttributes());
123
124 // Check if nodes can be combined
125 final List<ImmutableNode> children2 = new LinkedList<>(node2.getChildren());
126 node1.forEach(child1 -> {
127 final ImmutableNode child2 = findCombineNode(node1, node2, child1);
128 if (child2 != null) {
129 result.addChild(combine(child1, child2));
130 children2.remove(child2);
131 } else {
132 result.addChild(child1);
133 }
134 });
135
136 // Add remaining children of node 2
137 children2.forEach(result::addChild);
138
139 return result.create();
140 }
141
142 /**
143 * <p>
144 * Tries to find a child node of the second source node, with which a child of the first source node can be combined.
145 * During combining of the source nodes an iteration over the first source node's children is performed. For each child
146 * node it is checked whether a corresponding child node in the second source node exists. If this is the case, these
147 * corresponding child nodes are recursively combined and the result is added to the combined node. This method
148 * implements the checks whether such a recursive combination is possible. The actual implementation tests the following
149 * conditions:
150 * </p>
151 * <ul>
152 * <li>In both the first and the second source node there is only one child node with the given name (no list
153 * structures).</li>
154 * <li>The given name is not in the list of known list nodes, i.e. it was not passed to the {@code addListNode()}
155 * method.</li>
156 * <li>None of these matching child nodes has a value.</li>
157 * </ul>
158 * <p>
159 * If all of these tests are successful, the matching child node of the second source node is returned. Otherwise the
160 * result is <strong>null</strong>.
161 * </p>
162 *
163 * @param node1 the first source node
164 * @param node2 the second source node
165 * @param child the child node of the first source node to be checked
166 * @return the matching child node of the second source node or <strong>null</strong> if there is none
167 */
168 protected ImmutableNode findCombineNode(final ImmutableNode node1, final ImmutableNode node2, final ImmutableNode child) {
169 if (child.getValue() == null && !isListNode(child) && HANDLER.getChildrenCount(node1, child.getNodeName()) == 1
170 && HANDLER.getChildrenCount(node2, child.getNodeName()) == 1) {
171 final ImmutableNode child2 = HANDLER.getChildren(node2, child.getNodeName()).get(0);
172 if (child2.getValue() == null) {
173 return child2;
174 }
175 }
176 return null;
177 }
178 }