View Javadoc

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 <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 }