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