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