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 */
017package org.apache.commons.configuration2.tree;
018
019import java.util.ArrayList;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.List;
023
024/**
025 * <p>
026 * A simple data class used by {@link ExpressionEngine} to store
027 * the results of the {@code prepareAdd()} operation.
028 * </p>
029 * <p>
030 * If a new property is to be added to a configuration, the affected
031 * {@code Configuration} object must know, where in its hierarchy of
032 * configuration nodes new elements have to be added. This information is
033 * obtained by an {@code ExpressionEngine} object that interprets the key
034 * of the new property. This expression engine will pack all information
035 * necessary for the configuration to perform the add operation in an instance
036 * of this class.
037 * </p>
038 * <p>
039 * Information managed by this class contains:
040 * </p>
041 * <ul>
042 * <li>the configuration node, to which new elements must be added</li>
043 * <li>the name of the new node</li>
044 * <li>whether the new node is a child node or an attribute node</li>
045 * <li>if a whole branch is to be added at once, the names of all nodes between
046 * the parent node (the target of the add operation) and the new node</li>
047 * </ul>
048 *
049 * @since 1.3
050 * @version $Id: NodeAddData.java 1790899 2017-04-10 21:56:46Z ggregory $
051 * @param <T> the type of nodes this class can handle
052 */
053public class NodeAddData<T>
054{
055    /** Stores the parent node of the add operation. */
056    private final T parent;
057
058    /**
059     * Stores a list with the names of nodes that are on the path between the
060     * parent node and the new node.
061     */
062    private final List<String> pathNodes;
063
064    /** Stores the name of the new node. */
065    private final String newNodeName;
066
067    /** Stores the attribute flag. */
068    private final boolean attribute;
069
070    /**
071     * Creates a new instance of {@code NodeAddData} and initializes it.
072     *
073     * @param parentNode the parent node of the add operation
074     * @param newName the name of the new node
075     * @param isAttr flag whether the new node is an attribute
076     * @param intermediateNodes an optional collection with path nodes
077     */
078    public NodeAddData(T parentNode, String newName, boolean isAttr,
079            Collection<String> intermediateNodes)
080    {
081        parent = parentNode;
082        newNodeName = newName;
083        attribute = isAttr;
084        pathNodes = createPathNodes(intermediateNodes);
085    }
086
087    /**
088     * Returns a flag if the new node to be added is an attribute.
089     *
090     * @return <b>true</b> for an attribute node, <b>false</b> for a child
091     * node
092     */
093    public boolean isAttribute()
094    {
095        return attribute;
096    }
097
098    /**
099     * Returns the name of the new node.
100     *
101     * @return the new node's name
102     */
103    public String getNewNodeName()
104    {
105        return newNodeName;
106    }
107
108    /**
109     * Returns the parent node.
110     *
111     * @return the parent node
112     */
113    public T getParent()
114    {
115        return parent;
116    }
117
118    /**
119     * Returns a list with further nodes that must be added. This is needed if a
120     * complete branch is to be added at once. For instance, imagine that there
121     * exists only a node {@code database}. Now the key
122     * {@code database.connection.settings.username} (assuming the syntax
123     * of the default expression engine) is to be added. Then
124     * {@code username} is the name of the new node, but the nodes
125     * {@code connection} and {@code settings} must be added to
126     * the parent node first. In this example these names would be returned by
127     * this method.
128     *
129     * @return a list with the names of nodes that must be added as parents of
130     * the new node (never <b>null</b>)
131     */
132    public List<String> getPathNodes()
133    {
134        return pathNodes;
135    }
136
137    /**
138     * Creates the list with path nodes. Handles null input.
139     *
140     * @param intermediateNodes the nodes passed to the constructor
141     * @return an unmodifiable list of path nodes
142     */
143    private static List<String> createPathNodes(
144            Collection<String> intermediateNodes)
145    {
146        if (intermediateNodes == null)
147        {
148            return Collections.emptyList();
149        }
150        else
151        {
152            return Collections.unmodifiableList(new ArrayList<>(
153                    intermediateNodes));
154        }
155    }
156}