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