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 */ 017package org.apache.commons.configuration2.tree; 018 019import 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 keys (e.g. {@code getProperty()} 031 * or {@code addProperty()} do not interpret the passed in keys on their own, 032 * but delegate this task to an associated expression engine. This expression 033 * engine will then find out, which configuration nodes are addressed by the 034 * key. 035 * </p> 036 * <p> 037 * Separating the task of evaluating property keys from the configuration object 038 * has the advantage that multiple 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 * <p> 044 * An {@code ExpressionEngine} can deal with nodes of different types. To 045 * achieve this, a {@link NodeHandler} for the desired type must be passed to 046 * the methods. 047 * </p> 048 * 049 * @since 1.3 050 * @version $Id: ExpressionEngine.java 1624601 2014-09-12 18:04:36Z oheger $ 051 */ 052public interface ExpressionEngine 053{ 054 /** 055 * Finds the nodes and/or attributes that are matched by the specified key. 056 * This is the main method for interpreting property keys. An implementation 057 * must traverse the given root node and its children to find all results 058 * that are matched by the given key. If the key is not correct in the 059 * syntax provided by that implementation, it is free to throw a (runtime) 060 * exception indicating this error condition. The passed in 061 * {@code NodeHandler} can be used to gather the required information from 062 * the node object. 063 * 064 * @param <T> the type of the node to be processed 065 * @param root the root node of a hierarchy of nodes 066 * @param key the key to be evaluated 067 * @param handler the {@code NodeHandler} for accessing the node 068 * @return a list with the results that are matched by the key (should never 069 * be <b>null</b>) 070 */ 071 <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler); 072 073 /** 074 * Returns the key for the specified node in the expression language 075 * supported by an implementation. This method is called whenever a property 076 * key for a node has to be constructed, e.g. by the 077 * {@link org.apache.commons.configuration2.Configuration#getKeys() 078 * getKeys()} method. 079 * 080 * @param <T> the type of the node to be processed 081 * @param node the node, for which the key must be constructed 082 * @param parentKey the key of this node's parent (can be <b>null</b> for 083 * the root node) 084 * @param handler the {@code NodeHandler} for accessing the node 085 * @return this node's key 086 */ 087 <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler); 088 089 /** 090 * Returns the key of an attribute. The passed in {@code parentKey} must 091 * reference the parent node of the attribute. A concrete implementation 092 * must concatenate this parent key with the attribute name to a valid key 093 * for this attribute. 094 * 095 * @param parentKey the key to the node owning this attribute 096 * @param attributeName the name of the attribute in question 097 * @return the resulting key referencing this attribute 098 */ 099 String attributeKey(String parentKey, String attributeName); 100 101 /** 102 * Determines a "canonical" key for the specified node in the 103 * expression language supported by this implementation. This means that 104 * always a unique key if generated pointing to this specific node. For most 105 * concrete implementations, this means that an index is added to the node 106 * name to ensure that there are no ambiguities with child nodes having the 107 * same names. 108 * 109 * @param <T> the type of the node to be processed 110 * @param node the node, for which the key must be constructed 111 * @param parentKey the key of this node's parent (can be <b>null</b> for 112 * the root node) 113 * @param handler the {@code NodeHandler} for accessing the node 114 * @return the canonical key of this node 115 */ 116 <T> String canonicalKey(T node, String parentKey, NodeHandler<T> handler); 117 118 /** 119 * Returns information needed for an add operation. This method gets called 120 * when new properties are to be added to a configuration. An implementation 121 * has to interpret the specified key, find the parent node for the new 122 * elements, and provide all information about new nodes to be added. 123 * 124 * @param <T> the type of the node to be processed 125 * @param root the root node 126 * @param key the key for the new property 127 * @param handler the {@code NodeHandler} for accessing the node 128 * @return an object with all information needed for the add operation 129 */ 130 <T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler); 131}