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 attribures.
028     * </p>
029     *
030     * @since 1.3
031     * @author Oliver Heger
032     * @version $Id: ConfigurationNode.java 439648 2006-09-02 20:42:10Z oheger $
033     */
034    public interface ConfigurationNode
035    {
036        /**
037         * Returns the name of this node.
038         *
039         * @return the node name
040         */
041        String getName();
042    
043        /**
044         * Sets the name of this node.
045         *
046         * @param name the node name
047         */
048        void setName(String name);
049    
050        /**
051         * Returns the value of this node.
052         *
053         * @return the node's value
054         */
055        Object getValue();
056    
057        /**
058         * Sets the value of this node.
059         *
060         * @param val the node's value
061         */
062        void setValue(Object val);
063    
064        /**
065         * Returns this node's reference.
066         *
067         * @return the reference
068         */
069        Object getReference();
070    
071        /**
072         * Sets this node's reference. This reference can be used by concrete
073         * Configuration implementations to store data associated with each node. A
074         * XML based configuration for instance could here store a reference to the
075         * corresponding DOM element.
076         *
077         * @param ref the reference
078         */
079        void setReference(Object ref);
080    
081        /**
082         * Returns this node's parent. Can be <b>null</b>, then this node is the
083         * top level node.
084         *
085         * @return the parent of this node
086         */
087        ConfigurationNode getParentNode();
088    
089        /**
090         * Sets the parent of this node.
091         *
092         * @param parent the parent of this node
093         */
094        void setParentNode(ConfigurationNode parent);
095    
096        /**
097         * Adds a child to this node.
098         *
099         * @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    }