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 }