    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 Oliver Heger
    032     * @version $Id: ConfigurationNode.java 1152652 2011-07-31 21:49:49Z ebourg $
    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    }