##### Coverage Report - org.apache.commons.configuration.tree.ExpressionEngine

Classes in this File | Line Coverage | Branch Coverage | Complexity
ExpressionEngine |
N/A | N/A
N/A | N/A
| 1.0;1

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 |  |
     }