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