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 */
017package org.apache.commons.configuration.tree;
018
019import 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 */
036public 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}