Author: oheger
Date: Sat Feb 1 20:31:00 2014
New Revision: 1563464
URL: http://svn.apache.org/r1563464
Log:
Reworked ExpressionEngine interface.
An expression engine can now deal with nodes of different types; a NodeHandler
for the type desired has to be passed when invoking a method. A few methods
have been added for generating specific kinds of keys.
Modified:
commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
Modified:
commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java?rev=1563464&r1=1563463&r2=1563464&view=diff
==============================================================================
---
commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
(original)
+++
commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
Sat Feb 1 20:31:00 2014
@@ -27,56 +27,93 @@ import java.util.List;
* An <em>expression engine</em> knows how to map a key for a configuration's
* property to a single or a set of configuration nodes. Thus it defines the
way
* how properties are addressed in this configuration. Methods of a
- * configuration that have to handle property key (e.g.
- * {@code getProperty()} or {@code addProperty()} do not interpret
- * the passed in keys on their own, but delegate this task to an associated
- * expression engine. This expression engine will then find out, which
- * configuration nodes are addressed by the key.
+ * configuration that have to handle property keys (e.g. {@code getProperty()}
+ * or {@code addProperty()} do not interpret the passed in keys on their own,
+ * but delegate this task to an associated expression engine. This expression
+ * engine will then find out, which configuration nodes are addressed by the
+ * key.
* </p>
* <p>
* Separating the task of evaluating property keys from the configuration
object
- * has the advantage that many different expression languages (i.e. ways for
+ * has the advantage that multiple different expression languages (i.e. ways
for
* querying or setting properties) can be supported. Just set a suitable
* implementation of this interface as the configuration's expression engine,
* and you can use the syntax provided by this implementation.
* </p>
+ * <p>
+ * An {@code ExpressionEngine} can deal with nodes of different types. To
+ * achieve this, a {@link NodeHandler} for the desired type must be passed to
+ * the methods.
+ * </p>
*
* @since 1.3
- * @author <a
- * href="http://commons.apache.org/configuration/team-list.html";>Commons
- * Configuration team</a>
* @version $Id$
*/
public interface ExpressionEngine
{
/**
- * Finds the node(s) that is (are) matched by the specified key. This is
the
- * main method for interpreting property keys. An implementation must
- * traverse the given root node and its children to find all nodes that are
- * matched by the given key. If the key is not correct in the syntax
- * provided by that implementation, it is free to throw a (runtime)
- * exception indicating this error condition.
+ * Finds the nodes and/or attributes that are matched by the specified key.
+ * This is the main method for interpreting property keys. An
implementation
+ * must traverse the given root node and its children to find all results
+ * that are matched by the given key. If the key is not correct in the
+ * syntax provided by that implementation, it is free to throw a (runtime)
+ * exception indicating this error condition. The passed in
+ * {@code NodeHandler} can be used to gather the required information from
+ * the node object.
*
- * @param root the root node of a hierarchy of configuration nodes
+ * @param <T> the type of the node to be processed
+ * @param root the root node of a hierarchy of nodes
* @param key the key to be evaluated
- * @return a list with the nodes that are matched by the key (should never
- * be <b>null</b>)
+ * @param handler the {@code NodeHandler} for accessing the node
+ * @return a list with the results that are matched by the key (should
never
+ * be <b>null</b>)
*/
- List<ConfigurationNode> query(ConfigurationNode root, String key);
+ <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler);
/**
* Returns the key for the specified node in the expression language
* supported by an implementation. This method is called whenever a
property
* key for a node has to be constructed, e.g. by the
- * {@link org.apache.commons.configuration.Configuration#getKeys()
getKeys()}
- * method.
+ * {@link org.apache.commons.configuration.Configuration#getKeys()
+ * getKeys()} method.
*
+ * @param <T> the type of the node to be processed
* @param node the node, for which the key must be constructed
* @param parentKey the key of this node's parent (can be <b>null</b> for
- * the root node)
+ * the root node)
+ * @param handler the {@code NodeHandler} for accessing the node
* @return this node's key
*/
- String nodeKey(ConfigurationNode node, String parentKey);
+ <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler);
+
+ /**
+ * Returns the key of an attribute. The passed in {@code parentKey} must
+ * reference the parent node of the attribute. A concrete implementation
+ * must concatenate this parent key with the attribute name to a valid key
+ * for this attribute.
+ *
+ * @param parentKey the key to the node owning this attribute
+ * @param attributeName the name of the attribute in question
+ * @return the resulting key referencing this attribute
+ */
+ String attributeKey(String parentKey, String attributeName);
+
+ /**
+ * Determines a "canonical" key for the specified node in the
+ * expression language supported by this implementation. This means that
+ * always a unique key if generated pointing to this specific node. For
most
+ * concrete implementations, this means that an index is added to the node
+ * name to ensure that there are no ambiguities with child nodes having the
+ * same names.
+ *
+ * @param <T> the type of the node to be processed
+ * @param node the node, for which the key must be constructed
+ * @param parentKey the key of this node's parent (can be <b>null</b> for
+ * the root node)
+ * @param handler the {@code NodeHandler} for accessing the node
+ * @return the canonical key of this node
+ */
+ <T> String canonicalKey(T node, String parentKey, NodeHandler<T> handler);
/**
* Returns information needed for an add operation. This method gets called
@@ -84,9 +121,11 @@ public interface ExpressionEngine
* has to interpret the specified key, find the parent node for the new
* elements, and provide all information about new nodes to be added.
*
+ * @param <T> the type of the node to be processed
* @param root the root node
* @param key the key for the new property
+ * @param handler the {@code NodeHandler} for accessing the node
* @return an object with all information needed for the add operation
*/
- NodeAddData prepareAdd(ConfigurationNode root, String key);
+ <T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler);
}
