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.Collections;
    20  import java.util.LinkedList;
    21  import java.util.List;
    22
    23  /***
    24   * <p>
    25   * A simple data class used by <code>{@link ExpressionEngine}</code> to store
    26   * the results of the <code>prepareAdd()</code> operation.
    27   * </p>
    28   * <p>
    29   * If a new property is to be added to a configuration, the affected
    30   * <code>Configuration</code> object must know, where in its hierarchy of
    31   * configuration nodes new elements have to be added. This information is
    32   * obtained by an <code>ExpressionEngine</code> object that interprets the key
    33   * of the new property. This expression engine will pack all information
    34   * necessary for the configuration to perform the add operation in an instance
    35   * of this class.
    36   * </p>
    37   * <p>
    38   * Information managed by this class contains:
    39   * <ul>
    40   * <li>the configuration node, to which new elements must be added</li>
    41   * <li>the name of the new node</li>
    42   * <li>whether the new node is a child node or an attribute node</li>
    43   * <li>if a whole branch is to be added at once, the names of all nodes between
    44   * the parent node (the target of the add operation) and the new node</li>
    45   * </ul>
    46   * </p>
    47   *
    48   * @since 1.3
    49   * @author Oliver Heger
    50   */
    51  public class NodeAddData
    52  {
    53      /*** Stores the parent node of the add operation. */
    54      private ConfigurationNode parent;
    55
    56      /***
    57       * Stores a list with nodes that are on the path between the parent node and
    58       * the new node.
    59       */
    60      private List pathNodes;
    61
    62      /*** Stores the name of the new node. */
    63      private String newNodeName;
    64
    65      /*** Stores the attribute flag. */
    66      private boolean attribute;
    67
    68      /***
    69       * Creates a new, uninitialized instance of <code>NodeAddData</code>.
    70       */
    71      public NodeAddData()
    72      {
    73          this(null, null);
    74      }
    75
    76      /***
    77       * Creates a new instance of <code>NodeAddData</code> and sets the most
    78       * important data fields.
    79       *
    80       * @param parent the parent node
    81       * @param nodeName the name of the new node
    82       */
    83      public NodeAddData(ConfigurationNode parent, String nodeName)
    84      {
    85          setParent(parent);
    86          setNewNodeName(nodeName);
    87      }
    88
    89      /***
    90       * Returns a flag if the new node to be added is an attribute.
    91       *
    92       * @return <b>true</b> for an attribute node, <b>false</b> for a child
    93       * node
    94       */
    95      public boolean isAttribute()
    96      {
    97          return attribute;
    98      }
    99
    100     /***
    101      * Sets the attribute flag. This flag determines whether an attribute or a
    102      * child node will be added.
    103      *
    104      * @param attribute the attribute flag
    105      */
    106     public void setAttribute(boolean attribute)
    107     {
    108         this.attribute = attribute;
    109     }
    110
    111     /***
    112      * Returns the name of the new node.
    113      *
    114      * @return the new node's name
    115      */
    116     public String getNewNodeName()
    117     {
    118         return newNodeName;
    119     }
    120
    121     /***
    122      * Sets the name of the new node. A node with this name will be added to the
    123      * configuration's node hierarchy.
    124      *
    125      * @param newNodeName the name of the new node
    126      */
    127     public void setNewNodeName(String newNodeName)
    128     {
    129         this.newNodeName = newNodeName;
    130     }
    131
    132     /***
    133      * Returns the parent node.
    134      *
    135      * @return the parent node
    136      */
    137     public ConfigurationNode getParent()
    138     {
    139         return parent;
    140     }
    141
    142     /***
    143      * Sets the parent node. New nodes will be added to this node.
    144      *
    145      * @param parent the parent node
    146      */
    147     public void setParent(ConfigurationNode parent)
    148     {
    149         this.parent = parent;
    150     }
    151
    152     /***
    153      * Returns a list with further nodes that must be added. This is needed if a
    154      * complete branch is to be added at once. For instance imagine that there
    155      * exists only a node <code>database</code>. Now the key
    156      * <code>database.connection.settings.username</code> (assuming the syntax
    157      * of the default expression engine) is to be added. Then
    158      * <code>username</code> is the name of the new node, but the nodes
    159      * <code>connection</code> and <code>settings</code> must be added to
    160      * the parent node first. In this example these names would be returned by
    161      * this method.
    162      *
    163      * @return a list with the names of nodes that must be added as parents of
    164      * the new node (never <b>null</b>)
    165      */
    166     public List getPathNodes()
    167     {
    168         return (pathNodes != null) ? Collections.unmodifiableList(pathNodes)
    169                 : Collections.EMPTY_LIST;
    170     }
    171
    172     /***
    173      * Adds the name of a path node. With this method an additional node to be
    174      * added can be defined.
    175      *
    176      * @param nodeName the name of the node
    177      * @see #getPathNodes()
    178      */
    179     public void addPathNode(String nodeName)
    180     {
    181         if (pathNodes == null)
    182         {
    183             pathNodes = new LinkedList();
    184         }
    185         pathNodes.add(nodeName);
    186     }
    187 }