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 }