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 * https://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 * @param <T> the type of nodes this class can handle
46 * @since 1.3
47 */
48 public class NodeAddData<T> {
49
50 /**
51 * Creates the list with path nodes. Handles null input.
52 *
53 * @param intermediateNodes the nodes passed to the constructor
54 * @return an unmodifiable list of path nodes
55 */
56 private static List<String> createPathNodes(final Collection<String> intermediateNodes) {
57 if (intermediateNodes == null) {
58 return Collections.emptyList();
59 }
60 return Collections.unmodifiableList(new ArrayList<>(intermediateNodes));
61 }
62
63 /** Stores the parent node of the add operation. */
64 private final T parent;
65
66 /**
67 * Stores a list with the names of nodes that are on the path between the parent node and the new node.
68 */
69 private final List<String> pathNodes;
70
71 /** Stores the name of the new node. */
72 private final String newNodeName;
73
74 /** Stores the attribute flag. */
75 private final boolean attribute;
76
77 /**
78 * Creates a new instance of {@code NodeAddData} and initializes it.
79 *
80 * @param parentNode the parent node of the add operation
81 * @param newName the name of the new node
82 * @param isAttr flag whether the new node is an attribute
83 * @param intermediateNodes an optional collection with path nodes
84 */
85 public NodeAddData(final T parentNode, final String newName, final boolean isAttr, final Collection<String> intermediateNodes) {
86 parent = parentNode;
87 newNodeName = newName;
88 attribute = isAttr;
89 pathNodes = createPathNodes(intermediateNodes);
90 }
91
92 /**
93 * Gets the name of the new node.
94 *
95 * @return the new node's name
96 */
97 public String getNewNodeName() {
98 return newNodeName;
99 }
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 }