UnionCombiner.java

  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. import java.util.LinkedList;
  19. import java.util.List;

  20. /**
  21.  * <p>
  22.  * A specialized implementation of the {@code NodeCombiner} interface that constructs a union from two passed in node
  23.  * hierarchies.
  24.  * </p>
  25.  * <p>
  26.  * The given source hierarchies are traversed, and their nodes are added to the resulting structure. Under some
  27.  * circumstances two nodes can be combined rather than adding both. This is the case if both nodes are single children
  28.  * (no lists) of their parents and do not have values. The corresponding check is implemented in the
  29.  * {@code findCombineNode()} method.
  30.  * </p>
  31.  * <p>
  32.  * Sometimes it is not possible for this combiner to detect whether two nodes can be combined or not. Consider the
  33.  * following two node hierarchies:
  34.  * </p>
  35.  *
  36.  * <pre>
  37.  * Hierarchy 1:
  38.  *
  39.  * Database
  40.  *   +--Tables
  41.  *        +--Table
  42.  *             +--name [users]
  43.  *             +--fields
  44.  *                   +--field
  45.  *                   |    +--name [uid]
  46.  *                   +--field
  47.  *                   |    +--name [usrname]
  48.  *                     ...
  49.  * </pre>
  50.  *
  51.  * <pre>
  52.  * Hierarchy 2:
  53.  *
  54.  * Database
  55.  *   +--Tables
  56.  *        +--Table
  57.  *             +--name [documents]
  58.  *             +--fields
  59.  *                   +--field
  60.  *                   |    +--name [docid]
  61.  *                   +--field
  62.  *                   |    +--name [docname]
  63.  *                     ...
  64.  * </pre>
  65.  *
  66.  * <p>
  67.  * Both hierarchies contain data about database tables. Each describes a single table. If these hierarchies are to be
  68.  * combined, the result should probably look like the following:
  69.  * </p>
  70.  *
  71.  * <pre>
  72.  * Database
  73.  *   +--Tables
  74.  *        +--Table
  75.  *        |    +--name [users]
  76.  *        |    +--fields
  77.  *        |          +--field
  78.  *        |          |    +--name [uid]
  79.  *        |            ...
  80.  *        +--Table
  81.  *             +--name [documents]
  82.  *             +--fields
  83.  *                   +--field
  84.  *                   |    +--name [docid]
  85.  *                     ...
  86.  * </pre>
  87.  *
  88.  * <p>
  89.  * i.e. the {@code Tables} nodes should be combined, while the {@code Table} nodes should both be added to the resulting
  90.  * tree. From the combiner's point of view there is no difference between the {@code Tables} and the {@code Table} nodes
  91.  * in the source trees, so the developer has to help out and give a hint that the {@code Table} nodes belong to a list
  92.  * structure. This can be done using the {@code addListNode()} method; this method expects the name of a node, which
  93.  * should be treated as a list node. So if {@code addListNode("Table");} was called, the combiner knows that it must not
  94.  * combine the {@code Table} nodes, but add it both to the resulting tree.
  95.  * </p>
  96.  * <p>
  97.  * Another limitation is the handling of attributes: Attributes can only have a single value. So if two nodes are to be
  98.  * combined which both have an attribute with the same name, it is not possible to construct a proper union attribute.
  99.  * In this case, the attribute value from the first node is used.
  100.  * </p>
  101.  *
  102.  * @since 1.3
  103.  */
  104. public class UnionCombiner extends NodeCombiner {
  105.     /**
  106.      * Combines the given nodes to a new union node.
  107.      *
  108.      * @param node1 the first source node
  109.      * @param node2 the second source node
  110.      * @return the union node
  111.      */
  112.     @Override
  113.     public ImmutableNode combine(final ImmutableNode node1, final ImmutableNode node2) {
  114.         final ImmutableNode.Builder result = new ImmutableNode.Builder();
  115.         result.name(node1.getNodeName());

  116.         // attributes of the first node take precedence
  117.         result.addAttributes(node2.getAttributes());
  118.         result.addAttributes(node1.getAttributes());

  119.         // Check if nodes can be combined
  120.         final List<ImmutableNode> children2 = new LinkedList<>(node2.getChildren());
  121.         node1.forEach(child1 -> {
  122.             final ImmutableNode child2 = findCombineNode(node1, node2, child1);
  123.             if (child2 != null) {
  124.                 result.addChild(combine(child1, child2));
  125.                 children2.remove(child2);
  126.             } else {
  127.                 result.addChild(child1);
  128.             }
  129.         });

  130.         // Add remaining children of node 2
  131.         children2.forEach(result::addChild);

  132.         return result.create();
  133.     }

  134.     /**
  135.      * <p>
  136.      * Tries to find a child node of the second source node, with which a child of the first source node can be combined.
  137.      * During combining of the source nodes an iteration over the first source node's children is performed. For each child
  138.      * node it is checked whether a corresponding child node in the second source node exists. If this is the case, these
  139.      * corresponding child nodes are recursively combined and the result is added to the combined node. This method
  140.      * implements the checks whether such a recursive combination is possible. The actual implementation tests the following
  141.      * conditions:
  142.      * </p>
  143.      * <ul>
  144.      * <li>In both the first and the second source node there is only one child node with the given name (no list
  145.      * structures).</li>
  146.      * <li>The given name is not in the list of known list nodes, i.e. it was not passed to the {@code addListNode()}
  147.      * method.</li>
  148.      * <li>None of these matching child nodes has a value.</li>
  149.      * </ul>
  150.      * <p>
  151.      * If all of these tests are successful, the matching child node of the second source node is returned. Otherwise the
  152.      * result is <strong>null</strong>.
  153.      * </p>
  154.      *
  155.      * @param node1 the first source node
  156.      * @param node2 the second source node
  157.      * @param child the child node of the first source node to be checked
  158.      * @return the matching child node of the second source node or <strong>null</strong> if there is none
  159.      */
  160.     protected ImmutableNode findCombineNode(final ImmutableNode node1, final ImmutableNode node2, final ImmutableNode child) {
  161.         if (child.getValue() == null && !isListNode(child) && HANDLER.getChildrenCount(node1, child.getNodeName()) == 1
  162.             && HANDLER.getChildrenCount(node2, child.getNodeName()) == 1) {
  163.             final ImmutableNode child2 = HANDLER.getChildren(node2, child.getNodeName()).get(0);
  164.             if (child2.getValue() == null) {
  165.                 return child2;
  166.             }
  167.         }
  168.         return null;
  169.     }
  170. }