/*

  * Licensed to the Apache Software Foundation (ASF) under one or more

  * contributor license agreements.  See the NOTICE file distributed with

  * this work for additional information regarding copyright ownership.

  * The ASF licenses this file to You under the Apache License, Version 2.0

  * (the "License"); you may not use this file except in compliance with

  * the License.  You may obtain a copy of the License at

  *

  *     http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.configuration.tree;

 import java.util.Collections;

 import java.util.LinkedList;

 import java.util.List;

 /**

  * <p>

  * A simple data class used by <code>{@link ExpressionEngine}</code> to store

  * the results of the <code>prepareAdd()</code> operation.

  * </p>

  * <p>

  * If a new property is to be added to a configuration, the affected

  * <code>Configuration</code> object must know, where in its hierarchy of

  * configuration nodes new elements have to be added. This information is

  * obtained by an <code>ExpressionEngine</code> object that interprets the key

  * of the new property. This expression engine will pack all information

  * necessary for the configuration to perform the add operation in an instance

  * of this class.

  * </p>

  * <p>

  * Information managed by this class contains:

  * <ul>

  * <li>the configuration node, to which new elements must be added</li>

  * <li>the name of the new node</li>

  * <li>whether the new node is a child node or an attribute node</li>

  * <li>if a whole branch is to be added at once, the names of all nodes between

  * the parent node (the target of the add operation) and the new node</li>

  * </ul>

  * </p>

  *

  * @since 1.3

  * @author Oliver Heger

  */

 public class NodeAddData

 {

     /** Stores the parent node of the add operation. */

     private ConfigurationNode parent;

     /**

      * Stores a list with nodes that are on the path between the parent node and

      * the new node.

      */

     private List pathNodes;

     /** Stores the name of the new node. */

     private String newNodeName;

     /** Stores the attribute flag. */

     private boolean attribute;

     /**

      * Creates a new, uninitialized instance of <code>NodeAddData</code>.

      */

     public NodeAddData()

     {

         this(null, null);

     }

     /**

      * Creates a new instance of <code>NodeAddData</code> and sets the most

      * important data fields.

      *

      * @param parent the parent node

      * @param nodeName the name of the new node

      */

     public NodeAddData(ConfigurationNode parent, String nodeName)

     {

         setParent(parent);

         setNewNodeName(nodeName);

     }

     /**

      * Returns a flag if the new node to be added is an attribute.

      *

      * @return <b>true</b> for an attribute node, <b>false</b> for a child

      * node

      */

     public boolean isAttribute()

     {

         return attribute;

     }

     /**

      * Sets the attribute flag. This flag determines whether an attribute or a

      * child node will be added.

      *

      * @param attribute the attribute flag

      */

     public void setAttribute(boolean attribute)

     {

         this.attribute = attribute;

     }

     /**

      * Returns the name of the new node.

      *

      * @return the new node's name

      */

     public String getNewNodeName()

     {

         return newNodeName;

     }

     /**

      * Sets the name of the new node. A node with this name will be added to the

      * configuration's node hierarchy.

      *

      * @param newNodeName the name of the new node

      */

     public void setNewNodeName(String newNodeName)

     {

         this.newNodeName = newNodeName;

     }

     /**

      * Returns the parent node.

      *

      * @return the parent node

      */

     public ConfigurationNode getParent()

     {

         return parent;

     }

     /**

      * Sets the parent node. New nodes will be added to this node.

      *

      * @param parent the parent node

      */

     public void setParent(ConfigurationNode parent)

     {

         this.parent = parent;

     }

     /**

      * Returns a list with further nodes that must be added. This is needed if a

      * complete branch is to be added at once. For instance imagine that there

      * exists only a node <code>database</code>. Now the key

      * <code>database.connection.settings.username</code> (assuming the syntax

      * of the default expression engine) is to be added. Then

      * <code>username</code> is the name of the new node, but the nodes

      * <code>connection</code> and <code>settings</code> must be added to

      * the parent node first. In this example these names would be returned by

      * this method.

      *

      * @return a list with the names of nodes that must be added as parents of

      * the new node (never <b>null</b>)

      */

     public List getPathNodes()

     {

         return (pathNodes != null) ? Collections.unmodifiableList(pathNodes)

                 : Collections.EMPTY_LIST;

     }

     /**

      * Adds the name of a path node. With this method an additional node to be

      * added can be defined.

      *

      * @param nodeName the name of the node

      * @see #getPathNodes()

      */

     public void addPathNode(String nodeName)

     {

         if (pathNodes == null)

         {

             pathNodes = new LinkedList();

         }

         pathNodes.add(nodeName);

     }

 }