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 }