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