commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1563459 - /commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
Date Sat, 01 Feb 2014 20:07:06 GMT
Author: oheger
Date: Sat Feb  1 20:07:05 2014
New Revision: 1563459

URL: http://svn.apache.org/r1563459
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/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java

Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java?rev=1563459&r1=1563458&r2=1563459&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
(original)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/ExpressionEngine.java
Sat Feb  1 20:07:05 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 &quot;canonical&quot; 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);
 }



Mime
View raw message