    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    }