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()</code> or <code>addProperty()</code> 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   * Seperating 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 Oliver Heger
46   */
47  public interface ExpressionEngine
48  {
49      /***
50       * Finds the node(s) that is (are) matched by the specified key. This is the
51       * main method for interpreting property keys. An implementation must
52       * traverse the given root node and its children to find all nodes that are
53       * matched by the given key. If the key is not correct in the syntax
54       * provided by that implementation, it is free to throw a (runtime)
55       * exception indicating this error condition.
56       *
57       * @param root the root node of a hierarchy of configuration nodes
58       * @param key the key to be evaluated
59       * @return a list with the nodes that are matched by the key (should never
60       * be <b>null</b>)
61       */
62      List query(ConfigurationNode root, String key);
63  
64      /***
65       * Returns the key for the specified node in the expression language
66       * supported by an implementation. This method is called whenever a property
67       * key for a node has to be constructed, e.g. by the
68       * <code>{@link org.apache.commons.configuration.Configuration#getKeys() getKeys()}</code>
69       * method.
70       *
71       * @param node the node, for which the key must be constructed
72       * @param parentKey the key of this node's parent (can be <b>null</b> for
73       * the root node)
74       * @return this node's key
75       */
76      String nodeKey(ConfigurationNode node, String parentKey);
77  
78      /***
79       * Returns information needed for an add operation. This method gets called
80       * when new properties are to be added to a configuration. An implementation
81       * has to interpret the specified key, find the parent node for the new
82       * elements, and provide all information about new nodes to be added.
83       *
84       * @param root the root node
85       * @param key the key for the new property
86       * @return an object with all information needed for the add operation
87       */
88      NodeAddData prepareAdd(ConfigurationNode root, String key);
89  }