View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.configuration.tree;
    18
    19  import java.util.List;
    20
    21  /***
    22   * <p>
    23   * Definition of an interface for the nodes of a hierarchical configuration.
    24   * </p>
    25   * <p>
    26   * This interface defines a tree like structure for configuration data. A node
    27   * has a value and can have an arbitrary number of children and attribures.
    28   * </p>
    29   *
    30   * @since 1.3
    31   * @author Oliver Heger
    32   * @version $Id: ConfigurationNode.java 439648 2006-09-02 20:42:10Z oheger $
    33   */
    34  public interface ConfigurationNode
    35  {
    36      /***
    37       * Returns the name of this node.
    38       *
    39       * @return the node name
    40       */
    41      String getName();
    42
    43      /***
    44       * Sets the name of this node.
    45       *
    46       * @param name the node name
    47       */
    48      void setName(String name);
    49
    50      /***
    51       * Returns the value of this node.
    52       *
    53       * @return the node's value
    54       */
    55      Object getValue();
    56
    57      /***
    58       * Sets the value of this node.
    59       *
    60       * @param val the node's value
    61       */
    62      void setValue(Object val);
    63
    64      /***
    65       * Returns this node's reference.
    66       *
    67       * @return the reference
    68       */
    69      Object getReference();
    70
    71      /***
    72       * Sets this node's reference. This reference can be used by concrete
    73       * Configuration implementations to store data associated with each node. A
    74       * XML based configuration for instance could here store a reference to the
    75       * corresponding DOM element.
    76       *
    77       * @param ref the reference
    78       */
    79      void setReference(Object ref);
    80
    81      /***
    82       * Returns this node's parent. Can be <b>null</b>, then this node is the
    83       * top level node.
    84       *
    85       * @return the parent of this node
    86       */
    87      ConfigurationNode getParentNode();
    88
    89      /***
    90       * Sets the parent of this node.
    91       *
    92       * @param parent the parent of this node
    93       */
    94      void setParentNode(ConfigurationNode parent);
    95
    96      /***
    97       * Adds a child to this node.
    98       *
    99       * @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 }