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.configuration.tree; 018 019import java.util.List; 020 021/** 022 * <p> 023 * Definition of an interface for the nodes of a hierarchical configuration. 024 * </p> 025 * <p> 026 * This interface defines a tree like structure for configuration data. A node 027 * has a value and can have an arbitrary number of children and attributes. 028 * </p> 029 * 030 * @since 1.3 031 * @author <a 032 * href="http://commons.apache.org/configuration/team-list.html">Commons 033 * Configuration team</a> 034 * @version $Id: ConfigurationNode.java 1234988 2012-01-23 21:12:15Z oheger $ 035 */ 036public interface ConfigurationNode 037{ 038 /** 039 * Returns the name of this node. 040 * 041 * @return the node name 042 */ 043 String getName(); 044 045 /** 046 * Sets the name of this node. 047 * 048 * @param name the node name 049 */ 050 void setName(String name); 051 052 /** 053 * Returns the value of this node. 054 * 055 * @return the node's value 056 */ 057 Object getValue(); 058 059 /** 060 * Sets the value of this node. 061 * 062 * @param val the node's value 063 */ 064 void setValue(Object val); 065 066 /** 067 * Returns this node's reference. 068 * 069 * @return the reference 070 */ 071 Object getReference(); 072 073 /** 074 * Sets this node's reference. This reference can be used by concrete 075 * Configuration implementations to store data associated with each node. A 076 * XML based configuration for instance could here store a reference to the 077 * corresponding DOM element. 078 * 079 * @param ref the reference 080 */ 081 void setReference(Object ref); 082 083 /** 084 * Returns this node's parent. Can be <b>null</b>, then this node is the 085 * top level node. 086 * 087 * @return the parent of this node 088 */ 089 ConfigurationNode getParentNode(); 090 091 /** 092 * Sets the parent of this node. 093 * 094 * @param parent the parent of this node 095 */ 096 void setParentNode(ConfigurationNode parent); 097 098 /** 099 * Adds a child to this node. 100 * 101 * @param node the new child 102 */ 103 void addChild(ConfigurationNode node); 104 105 /** 106 * Returns a list with the child nodes of this node. The nodes in this list 107 * should be in the order they were inserted into this node. 108 * 109 * @return a list with the children of this node (never <b>null</b>) 110 */ 111 List<ConfigurationNode> getChildren(); 112 113 /** 114 * Returns the number of this node's children. 115 * 116 * @return the number of the children of this node 117 */ 118 int getChildrenCount(); 119 120 /** 121 * Returns a list with all children of this node with the given name. 122 * 123 * @param name the name of the searched children 124 * @return a list with all child nodes with this name (never <b>null</b>) 125 */ 126 List<ConfigurationNode> getChildren(String name); 127 128 /** 129 * Returns the number of children with the given name. 130 * 131 * @param name the name 132 * @return the number of children with this name 133 */ 134 int getChildrenCount(String name); 135 136 /** 137 * Returns the child node with the given index. If the index does not 138 * exist, an exception will be thrown. 139 * @param index the index of the child node (0-based) 140 * @return the child node with this index 141 */ 142 ConfigurationNode getChild(int index); 143 144 /** 145 * Removes the given node from this node's children. 146 * 147 * @param child the child node to be removed 148 * @return a flag if the node could be removed 149 */ 150 boolean removeChild(ConfigurationNode child); 151 152 /** 153 * Removes all child nodes of this node with the given name. 154 * 155 * @param childName the name of the children to be removed 156 * @return a flag if at least one child was removed 157 */ 158 boolean removeChild(String childName); 159 160 /** 161 * Removes all children from this node. 162 */ 163 void removeChildren(); 164 165 /** 166 * Returns a flag whether this node is an attribute. 167 * 168 * @return a flag whether this node is an attribute 169 */ 170 boolean isAttribute(); 171 172 /** 173 * Sets a flag whether this node is an attribute. 174 * 175 * @param f the attribute flag 176 */ 177 void setAttribute(boolean f); 178 179 /** 180 * Returns a list with this node's attributes. Attributes are also modeled 181 * as {@code ConfigurationNode} objects. 182 * 183 * @return a list with the attributes 184 */ 185 List<ConfigurationNode> getAttributes(); 186 187 /** 188 * Returns the number of attributes of this node. 189 * @return the number of attributes 190 */ 191 int getAttributeCount(); 192 193 /** 194 * Returns a list with the attribute nodes with the given name. Attributes 195 * with same names can be added multiple times, so the return value of this 196 * method is a list. 197 * 198 * @param name the name of the attribute 199 * @return the attribute nodes with this name (never <b>null</b>) 200 */ 201 List<ConfigurationNode> getAttributes(String name); 202 203 /** 204 * Returns the number of attributes with the given name. 205 * 206 * @param name the name of the attribute 207 * @return the number of attributes with this name 208 */ 209 int getAttributeCount(String name); 210 211 /** 212 * Returns the attribute node with the given index. If no such index exists, 213 * an exception will be thrown. 214 * @param index the index 215 * @return the attribute node with this index 216 */ 217 ConfigurationNode getAttribute(int index); 218 219 /** 220 * Removes the specified attribute from this node. 221 * 222 * @param node the attribute to remove 223 * @return a flag if the node could be removed 224 */ 225 boolean removeAttribute(ConfigurationNode node); 226 227 /** 228 * Removes all attributes with the given name. 229 * 230 * @param name the name of the attributes to be removed 231 * @return a flag if at least one attribute was removed 232 */ 233 boolean removeAttribute(String name); 234 235 /** 236 * Removes all attributes of this node. 237 */ 238 void removeAttributes(); 239 240 /** 241 * Adds the specified attribute to this node 242 * 243 * @param attr the attribute node 244 */ 245 void addAttribute(ConfigurationNode attr); 246 247 /** 248 * Returns a flag if this node is defined. This means that the node contains 249 * some data. 250 * 251 * @return a flag whether this node is defined 252 */ 253 boolean isDefined(); 254 255 /** 256 * Visits this node and all its sub nodes. This method provides a simple 257 * means for going through a hierarchical structure of configuration nodes. 258 * 259 * @see ConfigurationNodeVisitor 260 * @param visitor the visitor 261 */ 262 void visit(ConfigurationNodeVisitor visitor); 263 264 /** 265 * Returns a copy of this node. 266 * @return the copy 267 */ 268 Object clone(); 269}