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.configuration.tree; 18 19 import java.util.Collections; 20 import java.util.LinkedList; 21 import java.util.List; 22 23 /** 24 * <p> 25 * A simple data class used by {@link ExpressionEngine} to store 26 * 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 30 * {@code Configuration} object must know, where in its hierarchy of 31 * configuration nodes new elements have to be added. This information is 32 * obtained by an {@code ExpressionEngine} object that interprets the key 33 * of the new property. This expression engine will pack all information 34 * necessary for the configuration to perform the add operation in an instance 35 * of this class. 36 * </p> 37 * <p> 38 * Information managed by this class contains: 39 * <ul> 40 * <li>the configuration node, to which new elements must be added</li> 41 * <li>the name of the new node</li> 42 * <li>whether the new node is a child node or an attribute node</li> 43 * <li>if a whole branch is to be added at once, the names of all nodes between 44 * the parent node (the target of the add operation) and the new node</li> 45 * </ul> 46 * </p> 47 * 48 * @since 1.3 49 * @author <a 50 * href="http://commons.apache.org/configuration/team-list.html">Commons 51 * Configuration team</a> 52 * @version $Id: NodeAddData.java 1234988 2012-01-23 21:12:15Z oheger $ 53 */ 54 public class NodeAddData 55 { 56 /** Stores the parent node of the add operation. */ 57 private ConfigurationNode parent; 58 59 /** 60 * Stores a list with nodes that are on the path between the parent node and 61 * the new node. 62 */ 63 private List<String> pathNodes; 64 65 /** Stores the name of the new node. */ 66 private String newNodeName; 67 68 /** Stores the attribute flag. */ 69 private boolean attribute; 70 71 /** 72 * Creates a new, uninitialized instance of {@code NodeAddData}. 73 */ 74 public NodeAddData() 75 { 76 this(null, null); 77 } 78 79 /** 80 * Creates a new instance of {@code NodeAddData} and sets the most 81 * important data fields. 82 * 83 * @param parent the parent node 84 * @param nodeName the name of the new node 85 */ 86 public NodeAddData(ConfigurationNode parent, String nodeName) 87 { 88 setParent(parent); 89 setNewNodeName(nodeName); 90 } 91 92 /** 93 * Returns a flag if the new node to be added is an attribute. 94 * 95 * @return <b>true</b> for an attribute node, <b>false</b> for a child 96 * node 97 */ 98 public boolean isAttribute() 99 { 100 return attribute; 101 } 102 103 /** 104 * Sets the attribute flag. This flag determines whether an attribute or a 105 * child node will be added. 106 * 107 * @param attribute the attribute flag 108 */ 109 public void setAttribute(boolean attribute) 110 { 111 this.attribute = attribute; 112 } 113 114 /** 115 * Returns the name of the new node. 116 * 117 * @return the new node's name 118 */ 119 public String getNewNodeName() 120 { 121 return newNodeName; 122 } 123 124 /** 125 * Sets the name of the new node. A node with this name will be added to the 126 * configuration's node hierarchy. 127 * 128 * @param newNodeName the name of the new node 129 */ 130 public void setNewNodeName(String newNodeName) 131 { 132 this.newNodeName = newNodeName; 133 } 134 135 /** 136 * Returns the parent node. 137 * 138 * @return the parent node 139 */ 140 public ConfigurationNode getParent() 141 { 142 return parent; 143 } 144 145 /** 146 * Sets the parent node. New nodes will be added to this node. 147 * 148 * @param parent the parent node 149 */ 150 public void setParent(ConfigurationNode parent) 151 { 152 this.parent = parent; 153 } 154 155 /** 156 * Returns a list with further nodes that must be added. This is needed if a 157 * complete branch is to be added at once. For instance imagine that there 158 * exists only a node {@code database}. Now the key 159 * {@code database.connection.settings.username} (assuming the syntax 160 * of the default expression engine) is to be added. Then 161 * {@code username} is the name of the new node, but the nodes 162 * {@code connection} and {@code settings} must be added to 163 * the parent node first. In this example these names would be returned by 164 * this method. 165 * 166 * @return a list with the names of nodes that must be added as parents of 167 * the new node (never <b>null</b>) 168 */ 169 public List<String> getPathNodes() 170 { 171 if (pathNodes != null) 172 { 173 return Collections.unmodifiableList(pathNodes); 174 } 175 else 176 { 177 return Collections.emptyList(); 178 } 179 } 180 181 /** 182 * Adds the name of a path node. With this method an additional node to be 183 * added can be defined. 184 * 185 * @param nodeName the name of the node 186 * @see #getPathNodes() 187 */ 188 public void addPathNode(String nodeName) 189 { 190 if (pathNodes == null) 191 { 192 pathNodes = new LinkedList<String>(); 193 } 194 pathNodes.add(nodeName); 195 } 196 }