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