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; 020import java.util.Map; 021 022/** 023 * <p> 024 * Definition of an interface which allows resolving a (property) key for 025 * different manipulating operations. 026 * </p> 027 * <p> 028 * This interface is used when interacting with a node model. It is an 029 * abstraction over a concrete {@link ExpressionEngine} instance. It also 030 * implements some functionality for creating special helper objects for the 031 * processing of complex update operations. 032 * </p> 033 * 034 * @since 2.0 035 * @param <T> the type of the nodes supported by this resolver 036 */ 037public interface NodeKeyResolver<T> 038{ 039 /** 040 * Performs a query for the specified key on the given root node. This is a 041 * thin wrapper over the {@code query()} method of an 042 * {@link ExpressionEngine}. 043 * 044 * @param root the root node 045 * @param key the key to be resolved 046 * @param handler the {@code NodeHandler} 047 * @return a list with query results 048 */ 049 List<QueryResult<T>> resolveKey(T root, String key, NodeHandler<T> handler); 050 051 /** 052 * Performs a query for the specified key on the given root node returning 053 * only node results. Some operations require results of type node and do 054 * not support attributes (e.g. for tracking nodes). This operation can be 055 * used in such cases. It works like {@code resolveKey()}, but filters only 056 * for results of type node. 057 * 058 * @param root the root node 059 * @param key the key to be resolved 060 * @param handler the {@code NodeHandler} 061 * @return a list with the resolved nodes 062 */ 063 List<T> resolveNodeKey(T root, String key, NodeHandler<T> handler); 064 065 /** 066 * Resolves a key of an add operation. Result is a {@code NodeAddData} 067 * object containing all information for actually performing the add 068 * operation at the specified key. 069 * 070 * @param root the root node 071 * @param key the key to be resolved 072 * @param handler the {@code NodeHandler} 073 * @return a {@code NodeAddData} object to be used for the add operation 074 */ 075 NodeAddData<T> resolveAddKey(T root, String key, NodeHandler<T> handler); 076 077 /** 078 * Resolves a key for an update operation. Result is a 079 * {@code NodeUpdateData} object containing all information for actually 080 * performing the update operation at the specified key using the provided 081 * new value object. 082 * 083 * @param root the root node 084 * @param key the key to be resolved 085 * @param newValue the new value for the key to be updated; this can be a 086 * single value or a container for multiple values 087 * @param handler the {@code NodeHandler} 088 * @return a {@code NodeUpdateData} object to be used for this update 089 * operation 090 */ 091 NodeUpdateData<T> resolveUpdateKey(T root, String key, Object newValue, 092 NodeHandler<T> handler); 093 094 /** 095 * Generates a unique key for the specified node. This method is used if 096 * keys have to be generated for nodes received as query results. An 097 * implementation must generate a canonical key which is compatible with the 098 * current expression engine. The passed in map can be used by an 099 * implementation as cache. It is created initially by the caller and then 100 * passed in subsequent calls. An implementation may use this to avoid that 101 * keys for nodes already encountered have to be generated again. 102 * 103 * @param node the node in question 104 * @param cache a map serving as cache 105 * @param handler the {@code NodeHandler} 106 * @return a key for the specified node 107 */ 108 String nodeKey(T node, Map<T, String> cache, NodeHandler<T> handler); 109}