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.configuration.tree; 18 19 import java.util.List; 20 21 /** 22 * <p> 23 * Definition of an interface for the nodes of a hierarchical configuration. 24 * </p> 25 * <p> 26 * This interface defines a tree like structure for configuration data. A node 27 * has a value and can have an arbitrary number of children and attributes. 28 * </p> 29 * 30 * @since 1.3 31 * @author <a 32 * href="http://commons.apache.org/configuration/team-list.html">Commons 33 * Configuration team</a> 34 * @version $Id: ConfigurationNode.java 1234988 2012-01-23 21:12:15Z oheger $ 35 */ 36 public interface ConfigurationNode 37 { 38 /** 39 * Returns the name of this node. 40 * 41 * @return the node name 42 */ 43 String getName(); 44 45 /** 46 * Sets the name of this node. 47 * 48 * @param name the node name 49 */ 50 void setName(String name); 51 52 /** 53 * Returns the value of this node. 54 * 55 * @return the node's value 56 */ 57 Object getValue(); 58 59 /** 60 * Sets the value of this node. 61 * 62 * @param val the node's value 63 */ 64 void setValue(Object val); 65 66 /** 67 * Returns this node's reference. 68 * 69 * @return the reference 70 */ 71 Object getReference(); 72 73 /** 74 * Sets this node's reference. This reference can be used by concrete 75 * Configuration implementations to store data associated with each node. A 76 * XML based configuration for instance could here store a reference to the 77 * corresponding DOM element. 78 * 79 * @param ref the reference 80 */ 81 void setReference(Object ref); 82 83 /** 84 * Returns this node's parent. Can be <b>null</b>, then this node is the 85 * top level node. 86 * 87 * @return the parent of this node 88 */ 89 ConfigurationNode getParentNode(); 90 91 /** 92 * Sets the parent of this node. 93 * 94 * @param parent the parent of this node 95 */ 96 void setParentNode(ConfigurationNode parent); 97 98 /** 99 * 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 }