    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 <code>{@link ExpressionEngine}</code> to store
    026     * the results of the <code>prepareAdd()</code> operation.
    027     * </p>
    028     * <p>
    029     * If a new property is to be added to a configuration, the affected
    030     * <code>Configuration</code> 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</code> 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 Oliver Heger
    050     */
    051    public class NodeAddData
    052    {
    053        /** Stores the parent node of the add operation. */
    054        private ConfigurationNode parent;
    055
    056        /**
    057         * Stores a list with nodes that are on the path between the parent node and
    058         * the new node.
    059         */
    060        private List pathNodes;
    061
    062        /** Stores the name of the new node. */
    063        private String newNodeName;
    064
    065        /** Stores the attribute flag. */
    066        private boolean attribute;
    067
    068        /**
    069         * Creates a new, uninitialized instance of <code>NodeAddData</code>.
    070         */
    071        public NodeAddData()
    072        {
    073            this(null, null);
    074        }
    075
    076        /**
    077         * Creates a new instance of <code>NodeAddData</code> and sets the most
    078         * important data fields.
    079         *
    080         * @param parent the parent node
    081         * @param nodeName the name of the new node
    082         */
    083        public NodeAddData(ConfigurationNode parent, String nodeName)
    084        {
    085            setParent(parent);
    086            setNewNodeName(nodeName);
    087        }
    088
    089        /**
    090         * Returns a flag if the new node to be added is an attribute.
    091         *
    092         * @return <b>true</b> for an attribute node, <b>false</b> for a child
    093         * node
    094         */
    095        public boolean isAttribute()
    096        {
    097            return attribute;
    098        }
    099
    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    }