    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.Collections;
    020    import java.util.LinkedList;
    021    import java.util.List;
    022
    023    /**
    024     * <p>
    025     * A simple data class used by {@link ExpressionEngine} to store
    026     * the results of the {@code prepareAdd()} operation.
    027     * </p>
    028     * <p>
    029     * If a new property is to be added to a configuration, the affected
    030     * {@code Configuration} object must know, where in its hierarchy of
    031     * configuration nodes new elements have to be added. This information is
    032     * obtained by an {@code ExpressionEngine} object that interprets the key
    033     * of the new property. This expression engine will pack all information
    034     * necessary for the configuration to perform the add operation in an instance
    035     * of this class.
    036     * </p>
    037     * <p>
    038     * Information managed by this class contains:
    039     * <ul>
    040     * <li>the configuration node, to which new elements must be added</li>
    041     * <li>the name of the new node</li>
    042     * <li>whether the new node is a child node or an attribute node</li>
    043     * <li>if a whole branch is to be added at once, the names of all nodes between
    044     * the parent node (the target of the add operation) and the new node</li>
    045     * </ul>
    046     * </p>
    047     *
    048     * @since 1.3
    049     * @author <a
    050     * href="http://commons.apache.org/configuration/team-list.html">Commons
    051     * Configuration team</a>
    052     * @version $Id: NodeAddData.java 1234988 2012-01-23 21:12:15Z oheger $
    053     */
    054    public class NodeAddData
    055    {
    056        /** Stores the parent node of the add operation. */
    057        private ConfigurationNode parent;
    058
    059        /**
    060         * Stores a list with nodes that are on the path between the parent node and
    061         * the new node.
    062         */
    063        private List<String> pathNodes;
    064
    065        /** Stores the name of the new node. */
    066        private String newNodeName;
    067
    068        /** Stores the attribute flag. */
    069        private boolean attribute;
    070
    071        /**
    072         * Creates a new, uninitialized instance of {@code NodeAddData}.
    073         */
    074        public NodeAddData()
    075        {
    076            this(null, null);
    077        }
    078
    079        /**
    080         * Creates a new instance of {@code NodeAddData} and sets the most
    081         * important data fields.
    082         *
    083         * @param parent the parent node
    084         * @param nodeName the name of the new node
    085         */
    086        public NodeAddData(ConfigurationNode parent, String nodeName)
    087        {
    088            setParent(parent);
    089            setNewNodeName(nodeName);
    090        }
    091
    092        /**
    093         * Returns a flag if the new node to be added is an attribute.
    094         *
    095         * @return <b>true</b> for an attribute node, <b>false</b> for a child
    096         * node
    097         */
    098        public boolean isAttribute()
    099        {
    100            return attribute;
    101        }
    102
    103        /**
    104         * Sets the attribute flag. This flag determines whether an attribute or a
    105         * child node will be added.
    106         *
    107         * @param attribute the attribute flag
    108         */
    109        public void setAttribute(boolean attribute)
    110        {
    111            this.attribute = attribute;
    112        }
    113
    114        /**
    115         * Returns the name of the new node.
    116         *
    117         * @return the new node's name
    118         */
    119        public String getNewNodeName()
    120        {
    121            return newNodeName;
    122        }
    123
    124        /**
    125         * Sets the name of the new node. A node with this name will be added to the
    126         * configuration's node hierarchy.
    127         *
    128         * @param newNodeName the name of the new node
    129         */
    130        public void setNewNodeName(String newNodeName)
    131        {
    132            this.newNodeName = newNodeName;
    133        }
    134
    135        /**
    136         * Returns the parent node.
    137         *
    138         * @return the parent node
    139         */
    140        public ConfigurationNode getParent()
    141        {
    142            return parent;
    143        }
    144
    145        /**
    146         * Sets the parent node. New nodes will be added to this node.
    147         *
    148         * @param parent the parent node
    149         */
    150        public void setParent(ConfigurationNode parent)
    151        {
    152            this.parent = parent;
    153        }
    154
    155        /**
    156         * Returns a list with further nodes that must be added. This is needed if a
    157         * complete branch is to be added at once. For instance imagine that there
    158         * exists only a node {@code database}. Now the key
    159         * {@code database.connection.settings.username} (assuming the syntax
    160         * of the default expression engine) is to be added. Then
    161         * {@code username} is the name of the new node, but the nodes
    162         * {@code connection} and {@code settings} must be added to
    163         * the parent node first. In this example these names would be returned by
    164         * this method.
    165         *
    166         * @return a list with the names of nodes that must be added as parents of
    167         * the new node (never <b>null</b>)
    168         */
    169        public List<String> getPathNodes()
    170        {
    171            if (pathNodes != null)
    172            {
    173                return Collections.unmodifiableList(pathNodes);
    174            }
    175            else
    176            {
    177                return Collections.emptyList();
    178            }
    179        }
    180
    181        /**
    182         * Adds the name of a path node. With this method an additional node to be
    183         * added can be defined.
    184         *
    185         * @param nodeName the name of the node
    186         * @see #getPathNodes()
    187         */
    188        public void addPathNode(String nodeName)
    189        {
    190            if (pathNodes == null)
    191            {
    192                pathNodes = new LinkedList<String>();
    193            }
    194            pathNodes.add(nodeName);
    195        }
    196    }