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.ArrayList; 020import java.util.Collections; 021import java.util.Iterator; 022import java.util.LinkedList; 023import java.util.List; 024 025import org.apache.commons.lang3.builder.ToStringBuilder; 026 027/** 028 * <p> 029 * A class for selecting a specific node based on a key or a set of keys. 030 * </p> 031 * <p> 032 * An instance of this class is initialized with the key of a node. It is also possible to concatenate multiple keys - 033 * e.g. if a sub key is to be constructed from another sub key. {@code NodeSelector} provides the {@code select()} 034 * method which evaluates the wrapped keys on a specified root node and returns the resulting unique target node. The 035 * class expects that the key(s) stored in an instance select exactly one target node. If this is not the case, result 036 * is <b>null</b> indicating that the selection criteria are not sufficient. 037 * </p> 038 * <p> 039 * Implementation node: Instances of this class are immutable. They can be shared between arbitrary components. 040 * </p> 041 * 042 * @since 2.0 043 */ 044public class NodeSelector { 045 /** Stores the wrapped keys. */ 046 private final List<String> nodeKeys; 047 048 /** 049 * Creates a new instance of {@code NodeSelector} and initializes it with the key to the target node. 050 * 051 * @param key the key 052 */ 053 public NodeSelector(final String key) { 054 this(Collections.singletonList(key)); 055 } 056 057 /** 058 * Creates a new instance of {@code NodeSelector} and initializes it with the list of keys to be used as selection 059 * criteria. 060 * 061 * @param keys the keys for selecting nodes 062 */ 063 private NodeSelector(final List<String> keys) { 064 nodeKeys = keys; 065 } 066 067 /** 068 * Applies this {@code NodeSelector} on the specified root node. This method applies the selection criteria stored in 069 * this object and tries to determine a single target node. If this is successful, the target node is returned. 070 * Otherwise, result is <b>null</b>. 071 * 072 * @param root the root node on which to apply this selector 073 * @param resolver the {@code NodeKeyResolver} 074 * @param handler the {@code NodeHandler} 075 * @return the selected target node or <b>null</b> 076 */ 077 public ImmutableNode select(final ImmutableNode root, final NodeKeyResolver<ImmutableNode> resolver, final NodeHandler<ImmutableNode> handler) { 078 List<ImmutableNode> nodes = new LinkedList<>(); 079 final Iterator<String> itKeys = nodeKeys.iterator(); 080 getFilteredResults(root, resolver, handler, itKeys.next(), nodes); 081 082 while (itKeys.hasNext()) { 083 final String currentKey = itKeys.next(); 084 final List<ImmutableNode> currentResults = new LinkedList<>(); 085 nodes.forEach(currentRoot -> getFilteredResults(currentRoot, resolver, handler, currentKey, currentResults)); 086 nodes = currentResults; 087 } 088 089 return nodes.size() == 1 ? nodes.get(0) : null; 090 } 091 092 /** 093 * Creates a sub {@code NodeSelector} object which uses the key(s) of this selector plus the specified key as selection 094 * criteria. This is useful when another selection is to be performed on the results of a first selector. 095 * 096 * @param subKey the additional key for the sub selector 097 * @return the sub {@code NodeSelector} instance 098 */ 099 public NodeSelector subSelector(final String subKey) { 100 final List<String> keys = new ArrayList<>(nodeKeys.size() + 1); 101 keys.addAll(nodeKeys); 102 keys.add(subKey); 103 return new NodeSelector(keys); 104 } 105 106 /** 107 * Compares this object with another one. Two instances of {@code NodeSelector} are considered equal if they have the 108 * same keys as selection criteria. 109 * 110 * @param obj the object to be compared 111 * @return a flag whether these objects are equal 112 */ 113 @Override 114 public boolean equals(final Object obj) { 115 if (this == obj) { 116 return true; 117 } 118 if (!(obj instanceof NodeSelector)) { 119 return false; 120 } 121 122 final NodeSelector c = (NodeSelector) obj; 123 return nodeKeys.equals(c.nodeKeys); 124 } 125 126 /** 127 * Returns a hash code for this object. 128 * 129 * @return a hash code 130 */ 131 @Override 132 public int hashCode() { 133 return nodeKeys.hashCode(); 134 } 135 136 /** 137 * Returns a string representation for this object. This string contains the keys to be used as selection criteria. 138 * 139 * @return a string for this object 140 */ 141 @Override 142 public String toString() { 143 return new ToStringBuilder(this).append("keys", nodeKeys).toString(); 144 } 145 146 /** 147 * Executes a query for a given key and filters the results for nodes only. 148 * 149 * @param root the root node for the query 150 * @param resolver the {@code NodeKeyResolver} 151 * @param handler the {@code NodeHandler} 152 * @param key the key 153 * @param nodes here the results are stored 154 */ 155 private void getFilteredResults(final ImmutableNode root, final NodeKeyResolver<ImmutableNode> resolver, final NodeHandler<ImmutableNode> handler, 156 final String key, final List<ImmutableNode> nodes) { 157 final List<QueryResult<ImmutableNode>> results = resolver.resolveKey(root, key, handler); 158 results.forEach(result -> { 159 if (!result.isAttributeResult()) { 160 nodes.add(result.getNode()); 161 } 162 }); 163 } 164}