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.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 * Combines the given nodes to a new union node. 109 * 110 * @param node1 the first source node 111 * @param node2 the second source node 112 * @return the union node 113 */ 114 @Override 115 public ImmutableNode combine(final ImmutableNode node1, final ImmutableNode node2) { 116 final ImmutableNode.Builder result = new ImmutableNode.Builder(); 117 result.name(node1.getNodeName()); 118 119 // attributes of the first node take precedence 120 result.addAttributes(node2.getAttributes()); 121 result.addAttributes(node1.getAttributes()); 122 123 // Check if nodes can be combined 124 final List<ImmutableNode> children2 = new LinkedList<>(node2.getChildren()); 125 node1.forEach(child1 -> { 126 final ImmutableNode child2 = findCombineNode(node1, node2, child1); 127 if (child2 != null) { 128 result.addChild(combine(child1, child2)); 129 children2.remove(child2); 130 } else { 131 result.addChild(child1); 132 } 133 }); 134 135 // Add remaining children of node 2 136 children2.forEach(result::addChild); 137 138 return result.create(); 139 } 140 141 /** 142 * <p> 143 * Tries to find a child node of the second source node, with which a child of the first source node can be combined. 144 * During combining of the source nodes an iteration over the first source node's children is performed. For each child 145 * node it is checked whether a corresponding child node in the second source node exists. If this is the case, these 146 * corresponding child nodes are recursively combined and the result is added to the combined node. This method 147 * implements the checks whether such a recursive combination is possible. The actual implementation tests the following 148 * conditions: 149 * </p> 150 * <ul> 151 * <li>In both the first and the second source node there is only one child node with the given name (no list 152 * structures).</li> 153 * <li>The given name is not in the list of known list nodes, i.e. it was not passed to the {@code addListNode()} 154 * method.</li> 155 * <li>None of these matching child nodes has a value.</li> 156 * </ul> 157 * <p> 158 * If all of these tests are successful, the matching child node of the second source node is returned. Otherwise the 159 * result is <b>null</b>. 160 * </p> 161 * 162 * @param node1 the first source node 163 * @param node2 the second source node 164 * @param child the child node of the first source node to be checked 165 * @return the matching child node of the second source node or <b>null</b> if there is none 166 */ 167 protected ImmutableNode findCombineNode(final ImmutableNode node1, final ImmutableNode node2, final ImmutableNode child) { 168 if (child.getValue() == null && !isListNode(child) && HANDLER.getChildrenCount(node1, child.getNodeName()) == 1 169 && HANDLER.getChildrenCount(node2, child.getNodeName()) == 1) { 170 final ImmutableNode child2 = HANDLER.getChildren(node2, child.getNodeName()).get(0); 171 if (child2.getValue() == null) { 172 return child2; 173 } 174 } 175 return null; 176 } 177 }