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 */ 017package org.apache.commons.configuration2.tree; 018 019import java.util.Collections; 020import java.util.HashSet; 021import java.util.Set; 022 023/** 024 * <p> 025 * A base class for node combiner implementations. 026 * </p> 027 * <p> 028 * A <em>node combiner</em> is an object that knows how two hierarchical node 029 * structures can be combined into a single one. Of course, there are many 030 * possible ways of implementing such a combination, e.g. constructing a union, 031 * an intersection, or an "override" structure (were nodes in the first 032 * hierarchy take precedence over nodes in the second hierarchy). This abstract 033 * base class only provides some helper methods and defines the common interface 034 * for node combiners. Concrete sub classes will implement the diverse 035 * combination algorithms. 036 * </p> 037 * <p> 038 * For some concrete combiner implementations it is important to distinguish 039 * whether a node is a single node or whether it belongs to a list structure. 040 * Alone from the input structures, the combiner will not always be able to make 041 * this decision. So sometimes it may be necessary for the developer to 042 * configure the combiner and tell it, which nodes should be treated as list 043 * nodes. For this purpose the {@code addListNode()} method exists. It 044 * can be passed the name of a node, which should be considered a list node. 045 * </p> 046 * 047 * @since 1.3 048 */ 049public abstract class NodeCombiner 050{ 051 /** 052 * A default handler object for immutable nodes. This object can be used by 053 * derived classes for dealing with nodes. However, it provides only limited 054 * functionality; it supports only operations on child nodes, but no 055 * references to parent nodes. 056 */ 057 protected static final NodeHandler<ImmutableNode> HANDLER = 058 createNodeHandler(); 059 060 /** Stores a list with node names that are known to be list nodes. */ 061 private final Set<String> listNodes; 062 063 /** 064 * Creates a new instance of {@code NodeCombiner}. 065 */ 066 public NodeCombiner() 067 { 068 listNodes = new HashSet<>(); 069 } 070 071 /** 072 * Adds the name of a node to the list of known list nodes. This means that 073 * nodes with this name will never be combined. 074 * 075 * @param nodeName the name to be added 076 */ 077 public void addListNode(final String nodeName) 078 { 079 listNodes.add(nodeName); 080 } 081 082 /** 083 * Returns a set with the names of nodes that are known to be list nodes. 084 * 085 * @return a set with the names of list nodes 086 */ 087 public Set<String> getListNodes() 088 { 089 return Collections.unmodifiableSet(listNodes); 090 } 091 092 /** 093 * Checks if a node is a list node. This implementation tests if the given 094 * node name is contained in the set of known list nodes. Derived classes 095 * which use different criteria may overload this method. 096 * 097 * @param node the node to be tested 098 * @return a flag whether this is a list node 099 */ 100 public boolean isListNode(final ImmutableNode node) 101 { 102 return listNodes.contains(node.getNodeName()); 103 } 104 105 /** 106 * Combines the hierarchies represented by the given root nodes. This method 107 * must be defined in concrete sub classes with the implementation of a 108 * specific combination algorithm. 109 * 110 * @param node1 the first root node 111 * @param node2 the second root node 112 * @return the root node of the resulting combined node structure 113 */ 114 public abstract ImmutableNode combine(ImmutableNode node1, 115 ImmutableNode node2); 116 117 /** 118 * Creates a node handler object for immutable nodes which can be used by 119 * sub classes to perform advanced operations on nodes. 120 * 121 * @return the node handler implementation 122 */ 123 private static NodeHandler<ImmutableNode> createNodeHandler() 124 { 125 return new AbstractImmutableNodeHandler() 126 { 127 @Override 128 public ImmutableNode getParent(final ImmutableNode node) 129 { 130 return null; 131 } 132 133 @Override 134 public ImmutableNode getRootNode() 135 { 136 return null; 137 } 138 }; 139 } 140}