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