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 }