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 * @version $Id: NodeAddData.java 1842194 2018-09-27 22:24:23Z ggregory $ 051 * @param <T> the type of nodes this class can handle 052 */ 053public class NodeAddData<T> 054{ 055 /** Stores the parent node of the add operation. */ 056 private final T parent; 057 058 /** 059 * Stores a list with the names of nodes that are on the path between the 060 * parent node and the new node. 061 */ 062 private final List<String> pathNodes; 063 064 /** Stores the name of the new node. */ 065 private final String newNodeName; 066 067 /** Stores the attribute flag. */ 068 private final boolean attribute; 069 070 /** 071 * Creates a new instance of {@code NodeAddData} and initializes it. 072 * 073 * @param parentNode the parent node of the add operation 074 * @param newName the name of the new node 075 * @param isAttr flag whether the new node is an attribute 076 * @param intermediateNodes an optional collection with path nodes 077 */ 078 public NodeAddData(final T parentNode, final String newName, final boolean isAttr, 079 final Collection<String> intermediateNodes) 080 { 081 parent = parentNode; 082 newNodeName = newName; 083 attribute = isAttr; 084 pathNodes = createPathNodes(intermediateNodes); 085 } 086 087 /** 088 * Returns a flag if the new node to be added is an attribute. 089 * 090 * @return <b>true</b> for an attribute node, <b>false</b> for a child 091 * node 092 */ 093 public boolean isAttribute() 094 { 095 return attribute; 096 } 097 098 /** 099 * Returns the name of the new node. 100 * 101 * @return the new node's name 102 */ 103 public String getNewNodeName() 104 { 105 return newNodeName; 106 } 107 108 /** 109 * Returns the parent node. 110 * 111 * @return the parent node 112 */ 113 public T getParent() 114 { 115 return parent; 116 } 117 118 /** 119 * Returns a list with further nodes that must be added. This is needed if a 120 * complete branch is to be added at once. For instance, imagine that there 121 * exists only a node {@code database}. Now the key 122 * {@code database.connection.settings.username} (assuming the syntax 123 * of the default expression engine) is to be added. Then 124 * {@code username} is the name of the new node, but the nodes 125 * {@code connection} and {@code settings} must be added to 126 * the parent node first. In this example these names would be returned by 127 * this method. 128 * 129 * @return a list with the names of nodes that must be added as parents of 130 * the new node (never <b>null</b>) 131 */ 132 public List<String> getPathNodes() 133 { 134 return pathNodes; 135 } 136 137 /** 138 * Creates the list with path nodes. Handles null input. 139 * 140 * @param intermediateNodes the nodes passed to the constructor 141 * @return an unmodifiable list of path nodes 142 */ 143 private static List<String> createPathNodes( 144 final Collection<String> intermediateNodes) 145 { 146 if (intermediateNodes == null) 147 { 148 return Collections.emptyList(); 149 } 150 return Collections.unmodifiableList(new ArrayList<>( 151 intermediateNodes)); 152 } 153}