1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 <code>{@link ExpressionEngine}</code> to store
26 * the results of the <code>prepareAdd()</code> operation.
27 * </p>
28 * <p>
29 * If a new property is to be added to a configuration, the affected
30 * <code>Configuration</code> 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</code> 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 Oliver Heger
50 */
51 public class NodeAddData
52 {
53 /*** Stores the parent node of the add operation. */
54 private ConfigurationNode parent;
55
56 /***
57 * Stores a list with nodes that are on the path between the parent node and
58 * the new node.
59 */
60 private List pathNodes;
61
62 /*** Stores the name of the new node. */
63 private String newNodeName;
64
65 /*** Stores the attribute flag. */
66 private boolean attribute;
67
68 /***
69 * Creates a new, uninitialized instance of <code>NodeAddData</code>.
70 */
71 public NodeAddData()
72 {
73 this(null, null);
74 }
75
76 /***
77 * Creates a new instance of <code>NodeAddData</code> and sets the most
78 * important data fields.
79 *
80 * @param parent the parent node
81 * @param nodeName the name of the new node
82 */
83 public NodeAddData(ConfigurationNode parent, String nodeName)
84 {
85 setParent(parent);
86 setNewNodeName(nodeName);
87 }
88
89 /***
90 * Returns a flag if the new node to be added is an attribute.
91 *
92 * @return <b>true</b> for an attribute node, <b>false</b> for a child
93 * node
94 */
95 public boolean isAttribute()
96 {
97 return attribute;
98 }
99
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 }