/*
* 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.configuration.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>
*
* @version $Id: NodeSelector.java 1588832 2014-04-20 19:36:16Z oheger $
* @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 key to the target node.
*
* @param key the key
*/
public NodeSelector(String key)
{
this(Collections.singletonList(key));
}
/**
* 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(List<String> keys)
{
nodeKeys = keys;
}
/**
* 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(ImmutableNode root,
NodeKeyResolver<ImmutableNode> resolver,
NodeHandler<ImmutableNode> handler)
{
List<ImmutableNode> nodes = new LinkedList<ImmutableNode>();
Iterator<String> itKeys = nodeKeys.iterator();
getFilteredResults(root, resolver, handler, itKeys.next(), nodes);
while (itKeys.hasNext())
{
String currentKey = itKeys.next();
List<ImmutableNode> currentResults =
new LinkedList<ImmutableNode>();
for (ImmutableNode currentRoot : nodes)
{
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(String subKey)
{
List<String> keys = new ArrayList<String>(nodeKeys.size() + 1);
keys.addAll(nodeKeys);
keys.add(subKey);
return new NodeSelector(keys);
}
/**
* 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(Object obj)
{
if (this == obj)
{
return true;
}
if (!(obj instanceof NodeSelector))
{
return false;
}
NodeSelector c = (NodeSelector) obj;
return nodeKeys.equals(c.nodeKeys);
}
/**
* Returns a hash code for this object.
*
* @return a hash code
*/
@Override
public int hashCode()
{
return nodeKeys.hashCode();
}
/**
* 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();
}
/**
* 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(ImmutableNode root,
NodeKeyResolver<ImmutableNode> resolver,
NodeHandler<ImmutableNode> handler, String key,
List<ImmutableNode> nodes)
{
List<QueryResult<ImmutableNode>> results =
resolver.resolveKey(root, key, handler);
for (QueryResult<ImmutableNode> result : results)
{
if (!result.isAttributeResult())
{
nodes.add(result.getNode());
}
}
}
}