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.configuration2.tree; 18 19 import java.util.List; 20 21 /** 22 * <p> 23 * Definition of an interface for evaluating keys for hierarchical configurations. 24 * </p> 25 * <p> 26 * An <em>expression engine</em> knows how to map a key for a configuration's property to a single or a set of 27 * configuration nodes. Thus it defines the way how properties are addressed in this configuration. Methods of a 28 * configuration that have to handle property keys (e.g. {@code getProperty()} or {@code addProperty()} do not interpret 29 * the passed in keys on their own, but delegate this task to an associated expression engine. This expression engine 30 * will then find out, which configuration nodes are addressed by the key. 31 * </p> 32 * <p> 33 * Separating the task of evaluating property keys from the configuration object has the advantage that multiple 34 * different expression languages (i.e. ways for querying or setting properties) can be supported. Just set a suitable 35 * implementation of this interface as the configuration's expression engine, and you can use the syntax provided by 36 * this implementation. 37 * </p> 38 * <p> 39 * An {@code ExpressionEngine} can deal with nodes of different types. To achieve this, a {@link NodeHandler} for the 40 * desired type must be passed to the methods. 41 * </p> 42 * 43 * @since 1.3 44 */ 45 public interface ExpressionEngine { 46 /** 47 * Returns the key of an attribute. The passed in {@code parentKey} must reference the parent node of the attribute. A 48 * concrete implementation must concatenate this parent key with the attribute name to a valid key for this attribute. 49 * 50 * @param parentKey the key to the node owning this attribute 51 * @param attributeName the name of the attribute in question 52 * @return the resulting key referencing this attribute 53 */ 54 String attributeKey(String parentKey, String attributeName); 55 56 /** 57 * Determines a "canonical" key for the specified node in the expression language supported by this 58 * implementation. This means that always a unique key if generated pointing to this specific node. For most concrete 59 * implementations, this means that an index is added to the node name to ensure that there are no ambiguities with 60 * child nodes having the same names. 61 * 62 * @param <T> the type of the node to be processed 63 * @param node the node, for which the key must be constructed 64 * @param parentKey the key of this node's parent (can be <b>null</b> for the root node) 65 * @param handler the {@code NodeHandler} for accessing the node 66 * @return the canonical key of this node 67 */ 68 <T> String canonicalKey(T node, String parentKey, NodeHandler<T> handler); 69 70 /** 71 * Returns the key for the specified node in the expression language supported by an implementation. This method is 72 * called whenever a property key for a node has to be constructed, e.g. by the 73 * {@link org.apache.commons.configuration2.Configuration#getKeys() getKeys()} method. 74 * 75 * @param <T> the type of the node to be processed 76 * @param node the node, for which the key must be constructed 77 * @param parentKey the key of this node's parent (can be <b>null</b> for the root node) 78 * @param handler the {@code NodeHandler} for accessing the node 79 * @return this node's key 80 */ 81 <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler); 82 83 /** 84 * Returns information needed for an add operation. This method gets called when new properties are to be added to a 85 * configuration. An implementation has to interpret the specified key, find the parent node for the new elements, and 86 * provide all information about new nodes to be added. 87 * 88 * @param <T> the type of the node to be processed 89 * @param root the root node 90 * @param key the key for the new property 91 * @param handler the {@code NodeHandler} for accessing the node 92 * @return an object with all information needed for the add operation 93 */ 94 <T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler); 95 96 /** 97 * Finds the nodes and/or attributes that are matched by the specified key. This is the main method for interpreting 98 * property keys. An implementation must traverse the given root node and its children to find all results that are 99 * matched by the given key. If the key is not correct in the syntax provided by that implementation, it is free to 100 * throw a (runtime) exception indicating this error condition. The passed in {@code NodeHandler} can be used to gather 101 * the required information from the node object. 102 * 103 * @param <T> the type of the node to be processed 104 * @param root the root node of a hierarchy of nodes 105 * @param key the key to be evaluated 106 * @param handler the {@code NodeHandler} for accessing the node 107 * @return a list with the results that are matched by the key (should never be <b>null</b>) 108 */ 109 <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler); 110 }