View Javadoc

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 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 }