View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration.tree;
18  
19  import java.util.List;
20  
21  /**
22   * <p>
23   * Definition of an interface for evaluating keys for hierarchical
24   * configurations.
25   * </p>
26   * <p>
27   * An <em>expression engine</em> knows how to map a key for a configuration's
28   * property to a single or a set of configuration nodes. Thus it defines the way
29   * how properties are addressed in this configuration. Methods of a
30   * configuration that have to handle property key (e.g.
31   * {@code getProperty()} or {@code addProperty()} do not interpret
32   * the passed in keys on their own, but delegate this task to an associated
33   * expression engine. This expression engine will then find out, which
34   * configuration nodes are addressed by the key.
35   * </p>
36   * <p>
37   * Separating the task of evaluating property keys from the configuration object
38   * has the advantage that many different expression languages (i.e. ways for
39   * querying or setting properties) can be supported. Just set a suitable
40   * implementation of this interface as the configuration's expression engine,
41   * and you can use the syntax provided by this implementation.
42   * </p>
43   *
44   * @since 1.3
45   * @author <a
46   * href="http://commons.apache.org/configuration/team-list.html">Commons
47   * Configuration team</a>
48   * @version $Id: ExpressionEngine.java 1206474 2011-11-26 16:14:09Z oheger $
49   */
50  public interface ExpressionEngine
51  {
52      /**
53       * Finds the node(s) that is (are) matched by the specified key. This is the
54       * main method for interpreting property keys. An implementation must
55       * traverse the given root node and its children to find all nodes that are
56       * matched by the given key. If the key is not correct in the syntax
57       * provided by that implementation, it is free to throw a (runtime)
58       * exception indicating this error condition.
59       *
60       * @param root the root node of a hierarchy of configuration nodes
61       * @param key the key to be evaluated
62       * @return a list with the nodes that are matched by the key (should never
63       * be <b>null</b>)
64       */
65      List<ConfigurationNode> query(ConfigurationNode root, String key);
66  
67      /**
68       * Returns the key for the specified node in the expression language
69       * supported by an implementation. This method is called whenever a property
70       * key for a node has to be constructed, e.g. by the
71       * {@link org.apache.commons.configuration.Configuration#getKeys() getKeys()}
72       * method.
73       *
74       * @param node the node, for which the key must be constructed
75       * @param parentKey the key of this node's parent (can be <b>null</b> for
76       * the root node)
77       * @return this node's key
78       */
79      String nodeKey(ConfigurationNode node, String parentKey);
80  
81      /**
82       * Returns information needed for an add operation. This method gets called
83       * when new properties are to be added to a configuration. An implementation
84       * has to interpret the specified key, find the parent node for the new
85       * elements, and provide all information about new nodes to be added.
86       *
87       * @param root the root node
88       * @param key the key for the new property
89       * @return an object with all information needed for the add operation
90       */
91      NodeAddData prepareAdd(ConfigurationNode root, String key);
92  }