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
9
* http://www.apache.org/licenses/LICENSE-2.0
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.
17
package org.apache.commons.configuration.tree;
19
import java.util.List;
23
* Definition of an interface for evaluating keys for hierarchical
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.
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.
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 $
50
public interface ExpressionEngine
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.
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
65
List<ConfigurationNode> query(ConfigurationNode root, String key);
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()}
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
77
* @return this node's key
79
String nodeKey(ConfigurationNode node, String parentKey);
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.
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
91
NodeAddData prepareAdd(ConfigurationNode root, String key);