1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.configuration2.tree; 18 19 import java.util.ArrayList; 20 import java.util.Collection; 21 import java.util.Collections; 22 import java.util.List; 23 24 /** 25 * <p> 26 * A simple data class used by {@link ExpressionEngine} to store the results of the {@code prepareAdd()} operation. 27 * </p> 28 * <p> 29 * If a new property is to be added to a configuration, the affected {@code Configuration} object must know, where in 30 * its hierarchy of configuration nodes new elements have to be added. This information is obtained by an 31 * {@code ExpressionEngine} object that interprets the key of the new property. This expression engine will pack all 32 * information necessary for the configuration to perform the add operation in an instance of this class. 33 * </p> 34 * <p> 35 * Information managed by this class contains: 36 * </p> 37 * <ul> 38 * <li>the configuration node, to which new elements must be added</li> 39 * <li>the name of the new node</li> 40 * <li>whether the new node is a child node or an attribute node</li> 41 * <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 42 * operation) and the new node</li> 43 * </ul> 44 * 45 * @since 1.3 46 * @param <T> the type of nodes this class can handle 47 */ 48 public class NodeAddData<T> { 49 /** 50 * Creates the list with path nodes. Handles null input. 51 * 52 * @param intermediateNodes the nodes passed to the constructor 53 * @return an unmodifiable list of path nodes 54 */ 55 private static List<String> createPathNodes(final Collection<String> intermediateNodes) { 56 if (intermediateNodes == null) { 57 return Collections.emptyList(); 58 } 59 return Collections.unmodifiableList(new ArrayList<>(intermediateNodes)); 60 } 61 62 /** Stores the parent node of the add operation. */ 63 private final T parent; 64 65 /** 66 * Stores a list with the names of nodes that are on the path between the parent node and the new node. 67 */ 68 private final List<String> pathNodes; 69 70 /** Stores the name of the new node. */ 71 private final String newNodeName; 72 73 /** Stores the attribute flag. */ 74 private final boolean attribute; 75 76 /** 77 * Creates a new instance of {@code NodeAddData} and initializes it. 78 * 79 * @param parentNode the parent node of the add operation 80 * @param newName the name of the new node 81 * @param isAttr flag whether the new node is an attribute 82 * @param intermediateNodes an optional collection with path nodes 83 */ 84 public NodeAddData(final T parentNode, final String newName, final boolean isAttr, final Collection<String> intermediateNodes) { 85 parent = parentNode; 86 newNodeName = newName; 87 attribute = isAttr; 88 pathNodes = createPathNodes(intermediateNodes); 89 } 90 91 /** 92 * Gets the name of the new node. 93 * 94 * @return the new node's name 95 */ 96 public String getNewNodeName() { 97 return newNodeName; 98 } 99 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 }