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 attributes.
028 * </p>
029 *
030 * @since 1.3
031 * @author Oliver Heger
032 * @version $Id: ConfigurationNode.java 1152652 2011-07-31 21:49:49Z ebourg $
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 }