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 */
017 package org.apache.commons.configuration.tree;
018
019 import java.util.Collections;
020 import java.util.LinkedList;
021 import java.util.List;
022
023 /**
024 * <p>
025 * A simple data class used by {@link ExpressionEngine} to store
026 * 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
030 * {@code Configuration} object must know, where in its hierarchy of
031 * configuration nodes new elements have to be added. This information is
032 * obtained by an {@code ExpressionEngine} object that interprets the key
033 * of the new property. This expression engine will pack all information
034 * necessary for the configuration to perform the add operation in an instance
035 * of this class.
036 * </p>
037 * <p>
038 * Information managed by this class contains:
039 * <ul>
040 * <li>the configuration node, to which new elements must be added</li>
041 * <li>the name of the new node</li>
042 * <li>whether the new node is a child node or an attribute node</li>
043 * <li>if a whole branch is to be added at once, the names of all nodes between
044 * the parent node (the target of the add operation) and the new node</li>
045 * </ul>
046 * </p>
047 *
048 * @since 1.3
049 * @author <a
050 * href="http://commons.apache.org/configuration/team-list.html">Commons
051 * Configuration team</a>
052 * @version $Id: NodeAddData.java 1234988 2012-01-23 21:12:15Z oheger $
053 */
054 public class NodeAddData
055 {
056 /** Stores the parent node of the add operation. */
057 private ConfigurationNode parent;
058
059 /**
060 * Stores a list with nodes that are on the path between the parent node and
061 * the new node.
062 */
063 private List<String> pathNodes;
064
065 /** Stores the name of the new node. */
066 private String newNodeName;
067
068 /** Stores the attribute flag. */
069 private boolean attribute;
070
071 /**
072 * Creates a new, uninitialized instance of {@code NodeAddData}.
073 */
074 public NodeAddData()
075 {
076 this(null, null);
077 }
078
079 /**
080 * Creates a new instance of {@code NodeAddData} and sets the most
081 * important data fields.
082 *
083 * @param parent the parent node
084 * @param nodeName the name of the new node
085 */
086 public NodeAddData(ConfigurationNode parent, String nodeName)
087 {
088 setParent(parent);
089 setNewNodeName(nodeName);
090 }
091
092 /**
093 * Returns a flag if the new node to be added is an attribute.
094 *
095 * @return <b>true</b> for an attribute node, <b>false</b> for a child
096 * node
097 */
098 public boolean isAttribute()
099 {
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 }