    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 1842194 2018-09-27 22:24:23Z 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(final T parentNode, final String newName, final boolean isAttr,
    079            final 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            final Collection<String> intermediateNodes)
    145    {
    146        if (intermediateNodes == null)
    147        {
    148            return Collections.emptyList();
    149        }
    150        return Collections.unmodifiableList(new ArrayList<>(
    151                intermediateNodes));
    152    }
    153}