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.Set; 21 22 /** 23 * <p> 24 * Definition of an interface for accessing the data of a configuration node. 25 * </p> 26 * <p> 27 * Hierarchical configurations can deal with arbitrary node structures. In order to obtain information about a specific 28 * node object, a so-called {@code NodeHandler} is used. The handler provides a number of methods for querying the 29 * internal state of a node in a read-only way. 30 * </p> 31 * 32 * @param <T> the type of the nodes this handler deals with 33 */ 34 public interface NodeHandler<T> { 35 /** 36 * Gets an unmodifiable set with the names of all attributes of the specified node. 37 * 38 * @param node the node 39 * @return a set with the names of all attributes of this node 40 */ 41 Set<String> getAttributes(T node); 42 43 /** 44 * Gets the value of the specified attribute from the given node. If a concrete {@code NodeHandler} supports 45 * attributes with multiple values, result might be a collection. 46 * 47 * @param node the node 48 * @param name the name of the attribute 49 * @return the value of this attribute 50 */ 51 Object getAttributeValue(T node, String name); 52 53 /** 54 * Gets the child with the given index of the specified node. 55 * 56 * @param node the node 57 * @param index the index (0-based) 58 * @return the child with the given index 59 */ 60 T getChild(T node, int index); 61 62 /** 63 * Gets an unmodifiable list with all children of the specified node. 64 * 65 * @param node the node 66 * @return a list with the child nodes of this node 67 */ 68 List<T> getChildren(T node); 69 70 /** 71 * Gets an unmodifiable list of all children of the specified node with the given name. 72 * 73 * @param node the node 74 * @param name the name of the desired child nodes 75 * @return a list with all children with the given name 76 */ 77 List<T> getChildren(T node, String name); 78 79 /** 80 * Gets the number of children of the specified node with the given name. This method exists for performance reasons: 81 * for some node implementations it may be by far more efficient to count the children than to query a list of all 82 * children and determine its size. A concrete implementation can choose the most efficient way to determine the number 83 * of children. If a child name is passed in, only the children with this name are taken into account. If the name 84 * <b>null</b> is passed, the total number of children must be returned. 85 * 86 * @param node the node 87 * @param name the name of the children in question (can be <b>null</b> for all children) 88 * @return the number of the selected children 89 */ 90 int getChildrenCount(T node, String name); 91 92 /** 93 * Gets an unmodifiable list of all children of the specified node which are matched by the passed in 94 * {@code NodeMatcher} against the provided criterion. This method allows for advanced queries on a node's children. 95 * 96 * @param node the node 97 * @param matcher the {@code NodeMatcher} defining filter criteria 98 * @param criterion the criterion to be matched against; this object is passed to the {@code NodeMatcher} 99 * @param <C> the type of the criterion 100 * @return a list with all children matched by the matcher 101 */ 102 <C> List<T> getMatchingChildren(T node, NodeMatcher<C> matcher, C criterion); 103 104 /** 105 * Gets the number of children of the specified node which are matched by the given {@code NodeMatcher}. This is a 106 * more generic version of {@link #getChildrenCount(Object, String)}. It allows checking for arbitrary filter 107 * conditions. 108 * 109 * @param node the node 110 * @param matcher the {@code NodeMatcher} 111 * @param criterion the criterion to be passed to the {@code NodeMatcher} 112 * @param <C> the type of the criterion 113 * @return the number of matched children 114 */ 115 <C> int getMatchingChildrenCount(T node, NodeMatcher<C> matcher, C criterion); 116 117 /** 118 * Gets the parent of the specified node. 119 * 120 * @param node the node 121 * @return the parent node 122 */ 123 T getParent(T node); 124 125 /** 126 * Gets the root node of the underlying hierarchy. 127 * 128 * @return the current root node 129 */ 130 T getRootNode(); 131 132 /** 133 * Gets the value of the specified node. 134 * 135 * @param node the node 136 * @return the value of this node 137 */ 138 Object getValue(T node); 139 140 /** 141 * Returns a flag whether the passed in node has any attributes. 142 * 143 * @param node the node 144 * @return a flag whether this node has any attributes 145 */ 146 boolean hasAttributes(T node); 147 148 /** 149 * Returns the index of the given child node in the list of children of its parent. This method is the opposite 150 * operation of {@link #getChild(Object, int)}. This method returns 0 if the given node is the first child node with 151 * this name, 1 for the second child node and so on. If the node has no parent node or if it is an attribute, -1 is 152 * returned. 153 * 154 * @param parent the parent node 155 * @param child a child node whose index is to be retrieved 156 * @return the index of this child node 157 */ 158 int indexOfChild(T parent, T child); 159 160 /** 161 * Checks whether the specified node is defined. Nodes are "defined" if they contain any data, e.g. a value, 162 * or attributes, or defined children. 163 * 164 * @param node the node to test 165 * @return a flag whether the passed in node is defined 166 */ 167 boolean isDefined(T node); 168 169 /** 170 * Returns the name of the specified node 171 * 172 * @param node the node 173 * @return the name of this node 174 */ 175 String nodeName(T node); 176 }