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    }