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 <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 */
036 public 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 }