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.Set; 021 022/** 023 * <p> 024 * Definition of an interface for accessing the data of a configuration node. 025 * </p> 026 * <p> 027 * Hierarchical configurations can deal with arbitrary node structures. In order 028 * to obtain information about a specific node object, a so-called 029 * {@code NodeHandler} is used. The handler provides a number of methods for 030 * querying the internal state of a node in a read-only way. 031 * </p> 032 * 033 * @param <T> the type of the nodes this handler deals with 034 */ 035public interface NodeHandler<T> 036{ 037 /** 038 * Returns the name of the specified node 039 * 040 * @param node the node 041 * @return the name of this node 042 */ 043 String nodeName(T node); 044 045 /** 046 * Returns the value of the specified node. 047 * 048 * @param node the node 049 * @return the value of this node 050 */ 051 Object getValue(T node); 052 053 /** 054 * Returns the parent of the specified node. 055 * 056 * @param node the node 057 * @return the parent node 058 */ 059 T getParent(T node); 060 061 /** 062 * Returns an unmodifiable list with all children of the specified node. 063 * 064 * @param node the node 065 * @return a list with the child nodes of this node 066 */ 067 List<T> getChildren(T node); 068 069 /** 070 * Returns an unmodifiable list of all children of the specified node with 071 * the given name. 072 * 073 * @param node the node 074 * @param name the name of the desired child nodes 075 * @return a list with all children with the given name 076 */ 077 List<T> getChildren(T node, String name); 078 079 /** 080 * Returns an unmodifiable list of all children of the specified node which 081 * are matched by the passed in {@code NodeMatcher} against the provided 082 * criterion. This method allows for advanced queries on a node's children. 083 * 084 * @param node the node 085 * @param matcher the {@code NodeMatcher} defining filter criteria 086 * @param criterion the criterion to be matched against; this object is 087 * passed to the {@code NodeMatcher} 088 * @param <C> the type of the criterion 089 * @return a list with all children matched by the matcher 090 */ 091 <C> List<T> getMatchingChildren(T node, NodeMatcher<C> matcher, C criterion); 092 093 /** 094 * Returns the child with the given index of the specified node. 095 * 096 * @param node the node 097 * @param index the index (0-based) 098 * @return the child with the given index 099 */ 100 T getChild(T node, int index); 101 102 /** 103 * Returns the index of the given child node in the list of children of its 104 * parent. This method is the opposite operation of 105 * {@link #getChild(Object, int)}. This method returns 0 if the given node 106 * is the first child node with this name, 1 for the second child node and 107 * so on. If the node has no parent node or if it is an attribute, -1 is 108 * returned. 109 * 110 * @param parent the parent node 111 * @param child a child node whose index is to be retrieved 112 * @return the index of this child node 113 */ 114 int indexOfChild(T parent, T child); 115 116 /** 117 * Returns the number of children of the specified node with the given name. 118 * This method exists for performance reasons: for some node implementations 119 * it may be by far more efficient to count the children than to query a 120 * list of all children and determine its size. A concrete implementation 121 * can choose the most efficient way to determine the number of children. If 122 * a child name is passed in, only the children with this name are taken 123 * into account. If the name <b>null</b> is passed, the total number of 124 * children must be returned. 125 * 126 * @param node the node 127 * @param name the name of the children in question (can be <b>null</b> for 128 * all children) 129 * @return the number of the selected children 130 */ 131 int getChildrenCount(T node, String name); 132 133 /** 134 * Returns the number of children of the specified node which are matched by 135 * the given {@code NodeMatcher}. This is a more generic version of 136 * {@link #getChildrenCount(Object, String)}. It allows checking for 137 * arbitrary filter conditions. 138 * 139 * @param node the node 140 * @param matcher the {@code NodeMatcher} 141 * @param criterion the criterion to be passed to the {@code NodeMatcher} 142 * @param <C> the type of the criterion 143 * @return the number of matched children 144 */ 145 <C> int getMatchingChildrenCount(T node, NodeMatcher<C> matcher, C criterion); 146 147 /** 148 * Returns an unmodifiable set with the names of all attributes of the 149 * specified node. 150 * 151 * @param node the node 152 * @return a set with the names of all attributes of this node 153 */ 154 Set<String> getAttributes(T node); 155 156 /** 157 * Returns a flag whether the passed in node has any attributes. 158 * 159 * @param node the node 160 * @return a flag whether this node has any attributes 161 */ 162 boolean hasAttributes(T node); 163 164 /** 165 * Returns the value of the specified attribute from the given node. If a 166 * concrete {@code NodeHandler} supports attributes with multiple values, 167 * result might be a collection. 168 * 169 * @param node the node 170 * @param name the name of the attribute 171 * @return the value of this attribute 172 */ 173 Object getAttributeValue(T node, String name); 174 175 /** 176 * Checks whether the specified node is defined. Nodes are 177 * "defined" if they contain any data, e.g. a value, or 178 * attributes, or defined children. 179 * 180 * @param node the node to test 181 * @return a flag whether the passed in node is defined 182 */ 183 boolean isDefined(T node); 184 185 /** 186 * Returns the root node of the underlying hierarchy. 187 * 188 * @return the current root node 189 */ 190 T getRootNode(); 191}