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.ArrayList;
20 import java.util.Collections;
21 import java.util.Iterator;
22 import java.util.LinkedList;
23 import java.util.List;
24
25 import org.apache.commons.lang3.builder.ToStringBuilder;
26
27 /**
28 * <p>
29 * A class for selecting a specific node based on a key or a set of keys.
30 * </p>
31 * <p>
32 * An instance of this class is initialized with the key of a node. It is also possible to concatenate multiple keys -
33 * e.g. if a sub key is to be constructed from another sub key. {@code NodeSelector} provides the {@code select()}
34 * method which evaluates the wrapped keys on a specified root node and returns the resulting unique target node. The
35 * class expects that the key(s) stored in an instance select exactly one target node. If this is not the case, result
36 * is <b>null</b> indicating that the selection criteria are not sufficient.
37 * </p>
38 * <p>
39 * Implementation node: Instances of this class are immutable. They can be shared between arbitrary components.
40 * </p>
41 *
42 * @since 2.0
43 */
44 public class NodeSelector {
45 /** Stores the wrapped keys. */
46 private final List<String> nodeKeys;
47
48 /**
49 * Creates a new instance of {@code NodeSelector} and initializes it with the key to the target node.
50 *
51 * @param key the key
52 */
53 public NodeSelector(final String key) {
54 this(Collections.singletonList(key));
55 }
56
57 /**
58 * Creates a new instance of {@code NodeSelector} and initializes it with the list of keys to be used as selection
59 * criteria.
60 *
61 * @param keys the keys for selecting nodes
62 */
63 private NodeSelector(final List<String> keys) {
64 nodeKeys = keys;
65 }
66
67 /**
68 * Applies this {@code NodeSelector} on the specified root node. This method applies the selection criteria stored in
69 * this object and tries to determine a single target node. If this is successful, the target node is returned.
70 * Otherwise, result is <b>null</b>.
71 *
72 * @param root the root node on which to apply this selector
73 * @param resolver the {@code NodeKeyResolver}
74 * @param handler the {@code NodeHandler}
75 * @return the selected target node or <b>null</b>
76 */
77 public ImmutableNode select(final ImmutableNode root, final NodeKeyResolver<ImmutableNode> resolver, final NodeHandler<ImmutableNode> handler) {
78 List<ImmutableNode> nodes = new LinkedList<>();
79 final Iterator<String> itKeys = nodeKeys.iterator();
80 getFilteredResults(root, resolver, handler, itKeys.next(), nodes);
81
82 while (itKeys.hasNext()) {
83 final String currentKey = itKeys.next();
84 final List<ImmutableNode> currentResults = new LinkedList<>();
85 nodes.forEach(currentRoot -> getFilteredResults(currentRoot, resolver, handler, currentKey, currentResults));
86 nodes = currentResults;
87 }
88
89 return nodes.size() == 1 ? nodes.get(0) : null;
90 }
91
92 /**
93 * Creates a sub {@code NodeSelector} object which uses the key(s) of this selector plus the specified key as selection
94 * criteria. This is useful when another selection is to be performed on the results of a first selector.
95 *
96 * @param subKey the additional key for the sub selector
97 * @return the sub {@code NodeSelector} instance
98 */
99 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 }