| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.configuration2.tree; |
| |
| import java.util.ArrayList; |
| import java.util.Collections; |
| import java.util.Iterator; |
| import java.util.LinkedList; |
| import java.util.List; |
| |
| import org.apache.commons.lang3.builder.ToStringBuilder; |
| |
| /** |
| * <p> |
| * A class for selecting a specific node based on a key or a set of keys. |
| * </p> |
| * <p> |
| * An instance of this class is initialized with the key of a node. It is also possible to concatenate multiple keys - |
| * e.g. if a sub key is to be constructed from another sub key. {@code NodeSelector} provides the {@code select()} |
| * method which evaluates the wrapped keys on a specified root node and returns the resulting unique target node. The |
| * class expects that the key(s) stored in an instance select exactly one target node. If this is not the case, result |
| * is <b>null</b> indicating that the selection criteria are not sufficient. |
| * </p> |
| * <p> |
| * Implementation node: Instances of this class are immutable. They can be shared between arbitrary components. |
| * </p> |
| * |
| * @since 2.0 |
| */ |
| public class NodeSelector { |
| /** Stores the wrapped keys. */ |
| private final List<String> nodeKeys; |
| |
| /** |
| * Creates a new instance of {@code NodeSelector} and initializes it with the list of keys to be used as selection |
| * criteria. |
| * |
| * @param keys the keys for selecting nodes |
| */ |
| private NodeSelector(final List<String> keys) { |
| nodeKeys = keys; |
| } |
| |
| /** |
| * Creates a new instance of {@code NodeSelector} and initializes it with the key to the target node. |
| * |
| * @param key the key |
| */ |
| public NodeSelector(final String key) { |
| this(Collections.singletonList(key)); |
| } |
| |
| /** |
| * Compares this object with another one. Two instances of {@code NodeSelector} are considered equal if they have the |
| * same keys as selection criteria. |
| * |
| * @param obj the object to be compared |
| * @return a flag whether these objects are equal |
| */ |
| @Override |
| public boolean equals(final Object obj) { |
| if (this == obj) { |
| return true; |
| } |
| if (!(obj instanceof NodeSelector)) { |
| return false; |
| } |
| |
| final NodeSelector c = (NodeSelector) obj; |
| return nodeKeys.equals(c.nodeKeys); |
| } |
| |
| /** |
| * Executes a query for a given key and filters the results for nodes only. |
| * |
| * @param root the root node for the query |
| * @param resolver the {@code NodeKeyResolver} |
| * @param handler the {@code NodeHandler} |
| * @param key the key |
| * @param nodes here the results are stored |
| */ |
| private void getFilteredResults(final ImmutableNode root, final NodeKeyResolver<ImmutableNode> resolver, final NodeHandler<ImmutableNode> handler, |
| final String key, final List<ImmutableNode> nodes) { |
| final List<QueryResult<ImmutableNode>> results = resolver.resolveKey(root, key, handler); |
| results.forEach(result -> { |
| if (!result.isAttributeResult()) { |
| nodes.add(result.getNode()); |
| } |
| }); |
| } |
| |
| /** |
| * Returns a hash code for this object. |
| * |
| * @return a hash code |
| */ |
| @Override |
| public int hashCode() { |
| return nodeKeys.hashCode(); |
| } |
| |
| /** |
| * Applies this {@code NodeSelector} on the specified root node. This method applies the selection criteria stored in |
| * this object and tries to determine a single target node. If this is successful, the target node is returned. |
| * Otherwise, result is <b>null</b>. |
| * |
| * @param root the root node on which to apply this selector |
| * @param resolver the {@code NodeKeyResolver} |
| * @param handler the {@code NodeHandler} |
| * @return the selected target node or <b>null</b> |
| */ |
| public ImmutableNode select(final ImmutableNode root, final NodeKeyResolver<ImmutableNode> resolver, final NodeHandler<ImmutableNode> handler) { |
| List<ImmutableNode> nodes = new LinkedList<>(); |
| final Iterator<String> itKeys = nodeKeys.iterator(); |
| getFilteredResults(root, resolver, handler, itKeys.next(), nodes); |
| |
| while (itKeys.hasNext()) { |
| final String currentKey = itKeys.next(); |
| final List<ImmutableNode> currentResults = new LinkedList<>(); |
| nodes.forEach(currentRoot -> getFilteredResults(currentRoot, resolver, handler, currentKey, currentResults)); |
| nodes = currentResults; |
| } |
| |
| return nodes.size() == 1 ? nodes.get(0) : null; |
| } |
| |
| /** |
| * Creates a sub {@code NodeSelector} object which uses the key(s) of this selector plus the specified key as selection |
| * criteria. This is useful when another selection is to be performed on the results of a first selector. |
| * |
| * @param subKey the additional key for the sub selector |
| * @return the sub {@code NodeSelector} instance |
| */ |
| public NodeSelector subSelector(final String subKey) { |
| final List<String> keys = new ArrayList<>(nodeKeys.size() + 1); |
| keys.addAll(nodeKeys); |
| keys.add(subKey); |
| return new NodeSelector(keys); |
| } |
| |
| /** |
| * Returns a string representation for this object. This string contains the keys to be used as selection criteria. |
| * |
| * @return a string for this object |
| */ |
| @Override |
| public String toString() { |
| return new ToStringBuilder(this).append("keys", nodeKeys).toString(); |
| } |
| } |