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 }