1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.configuration2.tree;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.Collections;
22 import java.util.HashMap;
23 import java.util.Map;
24
25 /**
26 * <p>
27 * A simple data class used by node models to store parameters of an update operation.
28 * </p>
29 * <p>
30 * The {@code Configuration} interface provides a method for setting the value of a given key. The passed in value can
31 * be a single object or a collection of values. This makes an update operation rather complicated because a collection
32 * of query results selected by the passed in key has to be matched to another collection of values - and both
33 * collections can have different sizes. Therefore, an update operation may involve changing of existing nodes, adding
34 * new nodes (if there are more values than currently existing nodes), and removing nodes (if there are more existing
35 * nodes than provided values). This class collects all this information making it possible to actually perform the
36 * update based on a passed in instance.
37 * </p>
38 *
39 * @param <T> the type of nodes involved in this update operation
40 * @since 2.0
41 */
42 public class NodeUpdateData<T> {
43
44 /**
45 * Creates an unmodifiable defensive copy of the passed in collection with may be null.
46 *
47 * @param col the collection to be copied
48 * @param <T> the element type of the collection
49 * @return the unmodifiable copy
50 */
51 private static <T> Collection<T> copyCollection(final Collection<? extends T> col) {
52 if (col == null) {
53 return Collections.emptySet();
54 }
55 return Collections.unmodifiableCollection(new ArrayList<>(col));
56 }
57
58 /**
59 * Creates an unmodifiable defensive copy of the passed in map which may be null.
60 *
61 * @param map the map to be copied
62 * @param <K> the type of the keys involved
63 * @param <V> the type of the values involved
64 * @return the unmodifiable copy
65 */
66 private static <K, V> Map<K, V> copyMap(final Map<? extends K, ? extends V> map) {
67 if (map == null) {
68 return Collections.emptyMap();
69 }
70 return Collections.unmodifiableMap(new HashMap<>(map));
71 }
72
73 /** The map with the query results whose value has to be changed. */
74 private final Map<QueryResult<T>, Object> changedValues;
75
76 /** The collection with the new values to be added. */
77 private final Collection<Object> newValues;
78
79 /** The collection with query results about the nodes to be removed. */
80 private final Collection<QueryResult<T>> removedNodes;
81
82 /** The key of the current update operation. */
83 private final String key;
84
85 /**
86 * Creates a new instance of {@code NodeUpdateData} and initializes all its properties. All passed in collections are
87 * optional and can be <strong>null</strong>.
88 *
89 * @param changedValues the map defining the changed values
90 * @param newValues the collection with the new values
91 * @param removedNodes the collection with the nodes to be removed
92 * @param key the key of the update operation
93 */
94 public NodeUpdateData(final Map<QueryResult<T>, Object> changedValues, final Collection<Object> newValues, final Collection<QueryResult<T>> removedNodes,
95 final String key) {
96 this.changedValues = copyMap(changedValues);
97 this.newValues = copyCollection(newValues);
98 this.removedNodes = copyCollection(removedNodes);
99 this.key = key;
100 }
101
102 /**
103 * Gets an unmodifiable map with the values to be changed. The keys of the map are the query results for the nodes
104 * affected, the values are the new values to be assigned to these nodes.
105 *
106 * @return the map with values to be changed
107 */
108 public Map<QueryResult<T>, Object> getChangedValues() {
109 return changedValues;
110 }
111
112 /**
113 * Gets the key for this update operation.
114 *
115 * @return the key for this operation
116 */
117 public String getKey() {
118 return key;
119 }
120
121 /**
122 * Gets a collection with the values to be newly added. For these values new nodes have to be created and added under
123 * the key stored in this object.
124 *
125 * @return the collection with new values
126 */
127 public Collection<Object> getNewValues() {
128 return newValues;
129 }
130
131 /**
132 * Adds a collection with the nodes to be removed. These nodes are no longer needed and have to be removed from the node
133 * model processing this request.
134 *
135 * @return the collection with nodes to be removed
136 */
137 public Collection<QueryResult<T>> getRemovedNodes() {
138 return removedNodes;
139 }
140 }