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()</code> or <code>addProperty()</code> 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 * Seperating 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 Oliver Heger 046 */ 047 public interface ExpressionEngine 048 { 049 /** 050 * Finds the node(s) that is (are) matched by the specified key. This is the 051 * main method for interpreting property keys. An implementation must 052 * traverse the given root node and its children to find all nodes that are 053 * matched by the given key. If the key is not correct in the syntax 054 * provided by that implementation, it is free to throw a (runtime) 055 * exception indicating this error condition. 056 * 057 * @param root the root node of a hierarchy of configuration nodes 058 * @param key the key to be evaluated 059 * @return a list with the nodes that are matched by the key (should never 060 * be <b>null</b>) 061 */ 062 List query(ConfigurationNode root, String key); 063 064 /** 065 * Returns the key for the specified node in the expression language 066 * supported by an implementation. This method is called whenever a property 067 * key for a node has to be constructed, e.g. by the 068 * <code>{@link org.apache.commons.configuration.Configuration#getKeys() getKeys()}</code> 069 * method. 070 * 071 * @param node the node, for which the key must be constructed 072 * @param parentKey the key of this node's parent (can be <b>null</b> for 073 * the root node) 074 * @return this node's key 075 */ 076 String nodeKey(ConfigurationNode node, String parentKey); 077 078 /** 079 * Returns information needed for an add operation. This method gets called 080 * when new properties are to be added to a configuration. An implementation 081 * has to interpret the specified key, find the parent node for the new 082 * elements, and provide all information about new nodes to be added. 083 * 084 * @param root the root node 085 * @param key the key for the new property 086 * @return an object with all information needed for the add operation 087 */ 088 NodeAddData prepareAdd(ConfigurationNode root, String key); 089 }