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 <code>{@link ExpressionEngine}</code> to store
026 * the results of the <code>prepareAdd()</code> operation.
027 * </p>
028 * <p>
029 * If a new property is to be added to a configuration, the affected
030 * <code>Configuration</code> 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</code> 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 Oliver Heger
050 */
051 public class NodeAddData
052 {
053 /** Stores the parent node of the add operation. */
054 private ConfigurationNode parent;
055
056 /**
057 * Stores a list with nodes that are on the path between the parent node and
058 * the new node.
059 */
060 private List pathNodes;
061
062 /** Stores the name of the new node. */
063 private String newNodeName;
064
065 /** Stores the attribute flag. */
066 private boolean attribute;
067
068 /**
069 * Creates a new, uninitialized instance of <code>NodeAddData</code>.
070 */
071 public NodeAddData()
072 {
073 this(null, null);
074 }
075
076 /**
077 * Creates a new instance of <code>NodeAddData</code> and sets the most
078 * important data fields.
079 *
080 * @param parent the parent node
081 * @param nodeName the name of the new node
082 */
083 public NodeAddData(ConfigurationNode parent, String nodeName)
084 {
085 setParent(parent);
086 setNewNodeName(nodeName);
087 }
088
089 /**
090 * Returns a flag if the new node to be added is an attribute.
091 *
092 * @return <b>true</b> for an attribute node, <b>false</b> for a child
093 * node
094 */
095 public boolean isAttribute()
096 {
097 return attribute;
098 }
099
100 /**
101 * Sets the attribute flag. This flag determines whether an attribute or a
102 * child node will be added.
103 *
104 * @param attribute the attribute flag
105 */
106 public void setAttribute(boolean attribute)
107 {
108 this.attribute = attribute;
109 }
110
111 /**
112 * Returns the name of the new node.
113 *
114 * @return the new node's name
115 */
116 public String getNewNodeName()
117 {
118 return newNodeName;
119 }
120
121 /**
122 * Sets the name of the new node. A node with this name will be added to the
123 * configuration's node hierarchy.
124 *
125 * @param newNodeName the name of the new node
126 */
127 public void setNewNodeName(String newNodeName)
128 {
129 this.newNodeName = newNodeName;
130 }
131
132 /**
133 * Returns the parent node.
134 *
135 * @return the parent node
136 */
137 public ConfigurationNode getParent()
138 {
139 return parent;
140 }
141
142 /**
143 * Sets the parent node. New nodes will be added to this node.
144 *
145 * @param parent the parent node
146 */
147 public void setParent(ConfigurationNode parent)
148 {
149 this.parent = parent;
150 }
151
152 /**
153 * Returns a list with further nodes that must be added. This is needed if a
154 * complete branch is to be added at once. For instance imagine that there
155 * exists only a node <code>database</code>. Now the key
156 * <code>database.connection.settings.username</code> (assuming the syntax
157 * of the default expression engine) is to be added. Then
158 * <code>username</code> is the name of the new node, but the nodes
159 * <code>connection</code> and <code>settings</code> must be added to
160 * the parent node first. In this example these names would be returned by
161 * this method.
162 *
163 * @return a list with the names of nodes that must be added as parents of
164 * the new node (never <b>null</b>)
165 */
166 public List getPathNodes()
167 {
168 return (pathNodes != null) ? Collections.unmodifiableList(pathNodes)
169 : Collections.EMPTY_LIST;
170 }
171
172 /**
173 * Adds the name of a path node. With this method an additional node to be
174 * added can be defined.
175 *
176 * @param nodeName the name of the node
177 * @see #getPathNodes()
178 */
179 public void addPathNode(String nodeName)
180 {
181 if (pathNodes == null)
182 {
183 pathNodes = new LinkedList();
184 }
185 pathNodes.add(nodeName);
186 }
187 }