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