1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 attribures.
28 * </p>
29 *
30 * @since 1.3
31 * @author Oliver Heger
32 * @version $Id: ConfigurationNode.java 439648 2006-09-02 20:42:10Z oheger $
33 */
34 public interface ConfigurationNode
35 {
36 /***
37 * Returns the name of this node.
38 *
39 * @return the node name
40 */
41 String getName();
42
43 /***
44 * Sets the name of this node.
45 *
46 * @param name the node name
47 */
48 void setName(String name);
49
50 /***
51 * Returns the value of this node.
52 *
53 * @return the node's value
54 */
55 Object getValue();
56
57 /***
58 * Sets the value of this node.
59 *
60 * @param val the node's value
61 */
62 void setValue(Object val);
63
64 /***
65 * Returns this node's reference.
66 *
67 * @return the reference
68 */
69 Object getReference();
70
71 /***
72 * Sets this node's reference. This reference can be used by concrete
73 * Configuration implementations to store data associated with each node. A
74 * XML based configuration for instance could here store a reference to the
75 * corresponding DOM element.
76 *
77 * @param ref the reference
78 */
79 void setReference(Object ref);
80
81 /***
82 * Returns this node's parent. Can be <b>null</b>, then this node is the
83 * top level node.
84 *
85 * @return the parent of this node
86 */
87 ConfigurationNode getParentNode();
88
89 /***
90 * Sets the parent of this node.
91 *
92 * @param parent the parent of this node
93 */
94 void setParentNode(ConfigurationNode parent);
95
96 /***
97 * Adds a child to this node.
98 *
99 * @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 }