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: * Returns the name of this node.
037: *
038: * @return the node name
039: */
040: String getName();
041:
042: /**
043: * Sets the name of this node.
044: *
045: * @param name the node name
046: */
047: void setName(String name);
048:
049: /**
050: * Returns the value of this node.
051: *
052: * @return the node's value
053: */
054: Object getValue();
055:
056: /**
057: * Sets the value of this node.
058: *
059: * @param val the node's value
060: */
061: void setValue(Object val);
062:
063: /**
064: * Returns this node's reference.
065: *
066: * @return the reference
067: */
068: Object getReference();
069:
070: /**
071: * Sets this node's reference. This reference can be used by concrete
072: * Configuration implementations to store data associated with each node. A
073: * XML based configuration for instance could here store a reference to the
074: * corresponding DOM element.
075: *
076: * @param ref the reference
077: */
078: void setReference(Object ref);
079:
080: /**
081: * Returns this node's parent. Can be <b>null</b>, then this node is the
082: * top level node.
083: *
084: * @return the parent of this node
085: */
086: ConfigurationNode getParentNode();
087:
088: /**
089: * Sets the parent of this node.
090: *
091: * @param parent the parent of this node
092: */
093: void setParentNode(ConfigurationNode parent);
094:
095: /**
096: * Adds a child to this node.
097: *
098: * @param node the new child
099: */
100: void addChild(ConfigurationNode node);
101:
102: /**
103: * Returns a list with the child nodes of this node. The nodes in this list
104: * should be in the order they were inserted into this node.
105: *
106: * @return a list with the children of this node (never <b>null</b>)
107: */
108: List getChildren();
109:
110: /**
111: * Returns the number of this node's children.
112: *
113: * @return the number of the children of this node
114: */
115: int getChildrenCount();
116:
117: /**
118: * Returns a list with all children of this node with the given name.
119: *
120: * @param name the name of the searched children
121: * @return a list with all child nodes with this name (never <b>null</b>)
122: */
123: List getChildren(String name);
124:
125: /**
126: * Returns the number of children with the given name.
127: *
128: * @param name the name
129: * @return the number of children with this name
130: */
131: int getChildrenCount(String name);
132:
133: /**
134: * Returns the child node with the given index. If the index does not
135: * exist, an exception will be thrown.
136: * @param index the index of the child node (0-based)
137: * @return the child node with this index
138: */
139: ConfigurationNode getChild(int index);
140:
141: /**
142: * Removes the given node from this node's children.
143: *
144: * @param child the child node to be removed
145: * @return a flag if the node could be removed
146: */
147: boolean removeChild(ConfigurationNode child);
148:
149: /**
150: * Removes all child nodes of this node with the given name.
151: *
152: * @param childName the name of the children to be removed
153: * @return a flag if at least one child was removed
154: */
155: boolean removeChild(String childName);
156:
157: /**
158: * Removes all children from this node.
159: */
160: void removeChildren();
161:
162: /**
163: * Returns a flag whether this node is an attribute.
164: *
165: * @return a flag whether this node is an attribute
166: */
167: boolean isAttribute();
168:
169: /**
170: * Sets a flag whether this node is an attribute.
171: *
172: * @param f the attribute flag
173: */
174: void setAttribute(boolean f);
175:
176: /**
177: * Returns a list with this node's attributes. Attributes are also modeled
178: * as <code>ConfigurationNode</code> objects.
179: *
180: * @return a list with the attributes
181: */
182: List getAttributes();
183:
184: /**
185: * Returns the number of attributes of this node.
186: * @return the number of attributes
187: */
188: int getAttributeCount();
189:
190: /**
191: * Returns a list with the attribute nodes with the given name. Attributes
192: * with same names can be added multiple times, so the return value of this
193: * method is a list.
194: *
195: * @param name the name of the attribute
196: * @return the attribute nodes with this name (never <b>null</b>)
197: */
198: List getAttributes(String name);
199:
200: /**
201: * Returns the number of attributes with the given name.
202: *
203: * @param name the name of the attribute
204: * @return the number of attributes with this name
205: */
206: int getAttributeCount(String name);
207:
208: /**
209: * Returns the attribute node with the given index. If no such index exists,
210: * an exception will be thrown.
211: * @param index the index
212: * @return the attribute node with this index
213: */
214: ConfigurationNode getAttribute(int index);
215:
216: /**
217: * Removes the specified attribute from this node.
218: *
219: * @param node the attribute to remove
220: * @return a flag if the node could be removed
221: */
222: boolean removeAttribute(ConfigurationNode node);
223:
224: /**
225: * Removes all attributes with the given name.
226: *
227: * @param name the name of the attributes to be removed
228: * @return a flag if at least one attribute was removed
229: */
230: boolean removeAttribute(String name);
231:
232: /**
233: * Removes all attributes of this node.
234: */
235: void removeAttributes();
236:
237: /**
238: * Adds the specified attribute to this node
239: *
240: * @param attr the attribute node
241: */
242: void addAttribute(ConfigurationNode attr);
243:
244: /**
245: * Returns a flag if this node is defined. This means that the node contains
246: * some data.
247: *
248: * @return a flag whether this node is defined
249: */
250: boolean isDefined();
251:
252: /**
253: * Visits this node and all its sub nodes. This method provides a simple
254: * means for going through a hierarchical structure of configuration nodes.
255: *
256: * @see ConfigurationNodeVisitor
257: * @param visitor the visitor
258: */
259: void visit(ConfigurationNodeVisitor visitor);
260:
261: /**
262: * Returns a copy of this node.
263: * @return the copy
264: */
265: Object clone();
266: }
|