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 import java.util.Map; 21 22 /** 23 * <p> 24 * Definition of an interface which allows resolving a (property) key for different manipulating operations. 25 * </p> 26 * <p> 27 * This interface is used when interacting with a node model. It is an abstraction over a concrete 28 * {@link ExpressionEngine} instance. It also implements some functionality for creating special helper objects for the 29 * processing of complex update operations. 30 * </p> 31 * 32 * @since 2.0 33 * @param <T> the type of the nodes supported by this resolver 34 */ 35 public interface NodeKeyResolver<T> { 36 /** 37 * Generates a unique key for the specified node. This method is used if keys have to be generated for nodes received as 38 * query results. An implementation must generate a canonical key which is compatible with the current expression 39 * engine. The passed in map can be used by an implementation as cache. It is created initially by the caller and then 40 * passed in subsequent calls. An implementation may use this to avoid that keys for nodes already encountered have to 41 * be generated again. 42 * 43 * @param node the node in question 44 * @param cache a map serving as cache 45 * @param handler the {@code NodeHandler} 46 * @return a key for the specified node 47 */ 48 String nodeKey(T node, Map<T, String> cache, NodeHandler<T> handler); 49 50 /** 51 * Resolves a key of an add operation. Result is a {@code NodeAddData} object containing all information for actually 52 * performing the add operation at the specified key. 53 * 54 * @param root the root node 55 * @param key the key to be resolved 56 * @param handler the {@code NodeHandler} 57 * @return a {@code NodeAddData} object to be used for the add operation 58 */ 59 NodeAddData<T> resolveAddKey(T root, String key, NodeHandler<T> handler); 60 61 /** 62 * Performs a query for the specified key on the given root node. This is a thin wrapper over the {@code query()} method 63 * of an {@link ExpressionEngine}. 64 * 65 * @param root the root node 66 * @param key the key to be resolved 67 * @param handler the {@code NodeHandler} 68 * @return a list with query results 69 */ 70 List<QueryResult<T>> resolveKey(T root, String key, NodeHandler<T> handler); 71 72 /** 73 * Performs a query for the specified key on the given root node returning only node results. Some operations require 74 * results of type node and do not support attributes (e.g. for tracking nodes). This operation can be used in such 75 * cases. It works like {@code resolveKey()}, but filters only for results of type node. 76 * 77 * @param root the root node 78 * @param key the key to be resolved 79 * @param handler the {@code NodeHandler} 80 * @return a list with the resolved nodes 81 */ 82 List<T> resolveNodeKey(T root, String key, NodeHandler<T> handler); 83 84 /** 85 * Resolves a key for an update operation. Result is a {@code NodeUpdateData} object containing all information for 86 * actually performing the update operation at the specified key using the provided new value object. 87 * 88 * @param root the root node 89 * @param key the key to be resolved 90 * @param newValue the new value for the key to be updated; this can be a single value or a container for multiple 91 * values 92 * @param handler the {@code NodeHandler} 93 * @return a {@code NodeUpdateData} object to be used for this update operation 94 */ 95 NodeUpdateData<T> resolveUpdateKey(T root, String key, Object newValue, NodeHandler<T> handler); 96 }