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 */ 017package org.apache.commons.configuration2.tree; 018 019import java.util.ArrayList; 020import java.util.Collection; 021import java.util.Collections; 022import java.util.List; 023 024/** 025 * <p> 026 * A simple data class used by {@link ExpressionEngine} to store 027 * the results of the {@code prepareAdd()} operation. 028 * </p> 029 * <p> 030 * If a new property is to be added to a configuration, the affected 031 * {@code Configuration} object must know, where in its hierarchy of 032 * configuration nodes new elements have to be added. This information is 033 * obtained by an {@code ExpressionEngine} object that interprets the key 034 * of the new property. This expression engine will pack all information 035 * necessary for the configuration to perform the add operation in an instance 036 * of this class. 037 * </p> 038 * <p> 039 * Information managed by this class contains: 040 * </p> 041 * <ul> 042 * <li>the configuration node, to which new elements must be added</li> 043 * <li>the name of the new node</li> 044 * <li>whether the new node is a child node or an attribute node</li> 045 * <li>if a whole branch is to be added at once, the names of all nodes between 046 * the parent node (the target of the add operation) and the new node</li> 047 * </ul> 048 * 049 * @since 1.3 050 * @param <T> the type of nodes this class can handle 051 */ 052public class NodeAddData<T> 053{ 054 /** Stores the parent node of the add operation. */ 055 private final T parent; 056 057 /** 058 * Stores a list with the names of nodes that are on the path between the 059 * parent node and the new node. 060 */ 061 private final List<String> pathNodes; 062 063 /** Stores the name of the new node. */ 064 private final String newNodeName; 065 066 /** Stores the attribute flag. */ 067 private final boolean attribute; 068 069 /** 070 * Creates a new instance of {@code NodeAddData} and initializes it. 071 * 072 * @param parentNode the parent node of the add operation 073 * @param newName the name of the new node 074 * @param isAttr flag whether the new node is an attribute 075 * @param intermediateNodes an optional collection with path nodes 076 */ 077 public NodeAddData(final T parentNode, final String newName, final boolean isAttr, 078 final Collection<String> intermediateNodes) 079 { 080 parent = parentNode; 081 newNodeName = newName; 082 attribute = isAttr; 083 pathNodes = createPathNodes(intermediateNodes); 084 } 085 086 /** 087 * Returns a flag if the new node to be added is an attribute. 088 * 089 * @return <b>true</b> for an attribute node, <b>false</b> for a child 090 * node 091 */ 092 public boolean isAttribute() 093 { 094 return attribute; 095 } 096 097 /** 098 * Returns the name of the new node. 099 * 100 * @return the new node's name 101 */ 102 public String getNewNodeName() 103 { 104 return newNodeName; 105 } 106 107 /** 108 * Returns the parent node. 109 * 110 * @return the parent node 111 */ 112 public T getParent() 113 { 114 return parent; 115 } 116 117 /** 118 * Returns a list with further nodes that must be added. This is needed if a 119 * complete branch is to be added at once. For instance, imagine that there 120 * exists only a node {@code database}. Now the key 121 * {@code database.connection.settings.username} (assuming the syntax 122 * of the default expression engine) is to be added. Then 123 * {@code username} is the name of the new node, but the nodes 124 * {@code connection} and {@code settings} must be added to 125 * the parent node first. In this example these names would be returned by 126 * this method. 127 * 128 * @return a list with the names of nodes that must be added as parents of 129 * the new node (never <b>null</b>) 130 */ 131 public List<String> getPathNodes() 132 { 133 return pathNodes; 134 } 135 136 /** 137 * Creates the list with path nodes. Handles null input. 138 * 139 * @param intermediateNodes the nodes passed to the constructor 140 * @return an unmodifiable list of path nodes 141 */ 142 private static List<String> createPathNodes( 143 final Collection<String> intermediateNodes) 144 { 145 if (intermediateNodes == null) 146 { 147 return Collections.emptyList(); 148 } 149 return Collections.unmodifiableList(new ArrayList<>( 150 intermediateNodes)); 151 } 152}