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