Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ConfigurationNode |
|
| 1.0;1 |
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 | } |