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