001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.configuration.tree; 018 019 import java.util.List; 020 021 /** 022 * <p> 023 * Definition of an interface for evaluating keys for hierarchical 024 * configurations. 025 * </p> 026 * <p> 027 * An <em>expression engine</em> knows how to map a key for a configuration's 028 * property to a single or a set of configuration nodes. Thus it defines the way 029 * how properties are addressed in this configuration. Methods of a 030 * configuration that have to handle property key (e.g. 031 * {@code getProperty()} or {@code addProperty()} do not interpret 032 * the passed in keys on their own, but delegate this task to an associated 033 * expression engine. This expression engine will then find out, which 034 * configuration nodes are addressed by the key. 035 * </p> 036 * <p> 037 * Separating the task of evaluating property keys from the configuration object 038 * has the advantage that many different expression languages (i.e. ways for 039 * querying or setting properties) can be supported. Just set a suitable 040 * implementation of this interface as the configuration's expression engine, 041 * and you can use the syntax provided by this implementation. 042 * </p> 043 * 044 * @since 1.3 045 * @author <a 046 * href="http://commons.apache.org/configuration/team-list.html">Commons 047 * Configuration team</a> 048 * @version $Id: ExpressionEngine.java 1206474 2011-11-26 16:14:09Z oheger $ 049 */ 050 public interface ExpressionEngine 051 { 052 /** 053 * Finds the node(s) that is (are) matched by the specified key. This is the 054 * main method for interpreting property keys. An implementation must 055 * traverse the given root node and its children to find all nodes that are 056 * matched by the given key. If the key is not correct in the syntax 057 * provided by that implementation, it is free to throw a (runtime) 058 * exception indicating this error condition. 059 * 060 * @param root the root node of a hierarchy of configuration nodes 061 * @param key the key to be evaluated 062 * @return a list with the nodes that are matched by the key (should never 063 * be <b>null</b>) 064 */ 065 List<ConfigurationNode> query(ConfigurationNode root, String key); 066 067 /** 068 * Returns the key for the specified node in the expression language 069 * supported by an implementation. This method is called whenever a property 070 * key for a node has to be constructed, e.g. by the 071 * {@link org.apache.commons.configuration.Configuration#getKeys() getKeys()} 072 * method. 073 * 074 * @param node the node, for which the key must be constructed 075 * @param parentKey the key of this node's parent (can be <b>null</b> for 076 * the root node) 077 * @return this node's key 078 */ 079 String nodeKey(ConfigurationNode node, String parentKey); 080 081 /** 082 * Returns information needed for an add operation. This method gets called 083 * when new properties are to be added to a configuration. An implementation 084 * has to interpret the specified key, find the parent node for the new 085 * elements, and provide all information about new nodes to be added. 086 * 087 * @param root the root node 088 * @param key the key for the new property 089 * @return an object with all information needed for the add operation 090 */ 091 NodeAddData prepareAdd(ConfigurationNode root, String key); 092 }