001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.configuration.tree;
018    
019    import java.util.List;
020    
021    /**
022     * <p>
023     * Definition of an interface for the nodes of a hierarchical configuration.
024     * </p>
025     * <p>
026     * This interface defines a tree like structure for configuration data. A node
027     * has a value and can have an arbitrary number of children and attributes.
028     * </p>
029     *
030     * @since 1.3
031     * @author <a
032     * href="http://commons.apache.org/configuration/team-list.html">Commons
033     * Configuration team</a>
034     * @version $Id: ConfigurationNode.java 1234988 2012-01-23 21:12:15Z oheger $
035     */
036    public interface ConfigurationNode
037    {
038        /**
039         * Returns the name of this node.
040         *
041         * @return the node name
042         */
043        String getName();
044    
045        /**
046         * Sets the name of this node.
047         *
048         * @param name the node name
049         */
050        void setName(String name);
051    
052        /**
053         * Returns the value of this node.
054         *
055         * @return the node's value
056         */
057        Object getValue();
058    
059        /**
060         * Sets the value of this node.
061         *
062         * @param val the node's value
063         */
064        void setValue(Object val);
065    
066        /**
067         * Returns this node's reference.
068         *
069         * @return the reference
070         */
071        Object getReference();
072    
073        /**
074         * Sets this node's reference. This reference can be used by concrete
075         * Configuration implementations to store data associated with each node. A
076         * XML based configuration for instance could here store a reference to the
077         * corresponding DOM element.
078         *
079         * @param ref the reference
080         */
081        void setReference(Object ref);
082    
083        /**
084         * Returns this node's parent. Can be <b>null</b>, then this node is the
085         * top level node.
086         *
087         * @return the parent of this node
088         */
089        ConfigurationNode getParentNode();
090    
091        /**
092         * Sets the parent of this node.
093         *
094         * @param parent the parent of this node
095         */
096        void setParentNode(ConfigurationNode parent);
097    
098        /**
099         * 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    }