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 * http://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.collections4;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.HashSet;
22 import java.util.List;
23 import java.util.Set;
24
25 import org.apache.commons.collections4.bag.HashBag;
26 import org.apache.commons.collections4.multimap.ArrayListValuedHashMap;
27 import org.apache.commons.collections4.multimap.HashSetValuedHashMap;
28 import org.apache.commons.collections4.multimap.TransformedMultiValuedMap;
29 import org.apache.commons.collections4.multimap.UnmodifiableMultiValuedMap;
30
31 /**
32 * Provides utility methods and decorators for {@link MultiValuedMap} instances.
33 * <p>
34 * It contains various type safe and null safe methods. Additionally, it provides
35 * the following decorators:
36 * </p>
37 * <ul>
38 * <li>{@link #unmodifiableMultiValuedMap(MultiValuedMap)}</li>
39 * <li>{@link #transformedMultiValuedMap(MultiValuedMap, Transformer, Transformer)}</li>
40 * </ul>
41 *
42 * @since 4.1
43 */
44 public class MultiMapUtils {
45
46 /**
47 * An empty {@link UnmodifiableMultiValuedMap}.
48 */
49 @SuppressWarnings({ "rawtypes", "unchecked" })
50 public static final MultiValuedMap EMPTY_MULTI_VALUED_MAP =
51 UnmodifiableMultiValuedMap.unmodifiableMultiValuedMap(new ArrayListValuedHashMap(0, 0));
52
53 /**
54 * Returns an immutable empty {@code MultiValuedMap} if the argument is
55 * {@code null}, or the argument itself otherwise.
56 *
57 * @param <K> the type of key in the map
58 * @param <V> the type of value in the map
59 * @param map the map, may be null
60 * @return an empty {@link MultiValuedMap} if the argument is null
61 */
62 @SuppressWarnings("unchecked")
63 public static <K, V> MultiValuedMap<K, V> emptyIfNull(final MultiValuedMap<K, V> map) {
64 return map == null ? EMPTY_MULTI_VALUED_MAP : map;
65 }
66
67 /**
68 * Returns immutable EMPTY_MULTI_VALUED_MAP with generic type safety.
69 *
70 * @param <K> the type of key in the map
71 * @param <V> the type of value in the map
72 * @return immutable and empty {@code MultiValuedMap}
73 */
74 @SuppressWarnings("unchecked")
75 public static <K, V> MultiValuedMap<K, V> emptyMultiValuedMap() {
76 return EMPTY_MULTI_VALUED_MAP;
77 }
78
79 // Null safe methods
80
81 /**
82 * Gets a Collection from {@code MultiValuedMap} in a null-safe manner.
83 *
84 * @param <K> the key type
85 * @param <V> the value type
86 * @param map the {@link MultiValuedMap} to use
87 * @param key the key to look up
88 * @return the Collection in the {@link MultiValuedMap}, or null if input map is null
89 */
90 public static <K, V> Collection<V> getCollection(final MultiValuedMap<K, V> map, final K key) {
91 if (map != null) {
92 return map.get(key);
93 }
94 return null;
95 }
96
97 /**
98 * Gets a Bag from {@code MultiValuedMap} in a null-safe manner.
99 *
100 * @param <K> the key type
101 * @param <V> the value type
102 * @param map the {@link MultiValuedMap} to use
103 * @param key the key to look up
104 * @return the Collection in the {@link MultiValuedMap} as Bag, or null if input map is null
105 */
106 public static <K, V> Bag<V> getValuesAsBag(final MultiValuedMap<K, V> map, final K key) {
107 if (map != null) {
108 final Collection<V> col = map.get(key);
109 if (col instanceof Bag) {
110 return (Bag<V>) col;
111 }
112 return new HashBag<>(col);
113 }
114 return null;
115 }
116
117 /**
118 * Gets a List from {@code MultiValuedMap} in a null-safe manner.
119 *
120 * @param <K> the key type
121 * @param <V> the value type
122 * @param map the {@link MultiValuedMap} to use
123 * @param key the key to look up
124 * @return the Collection in the {@link MultiValuedMap} as List, or null if input map is null
125 */
126 public static <K, V> List<V> getValuesAsList(final MultiValuedMap<K, V> map, final K key) {
127 if (map != null) {
128 final Collection<V> col = map.get(key);
129 if (col instanceof List) {
130 return (List<V>) col;
131 }
132 return new ArrayList<>(col);
133 }
134 return null;
135 }
136
137 // TODO: review the getValuesAsXXX methods - depending on the actual MultiValuedMap type, changes
138 // to the returned collection might update the backing map. This should be clarified and/or prevented.
139
140 /**
141 * Gets a Set from {@code MultiValuedMap} in a null-safe manner.
142 *
143 * @param <K> the key type
144 * @param <V> the value type
145 * @param map the {@link MultiValuedMap} to use
146 * @param key the key to look up
147 * @return the Collection in the {@link MultiValuedMap} as Set, or null if input map is null
148 */
149 public static <K, V> Set<V> getValuesAsSet(final MultiValuedMap<K, V> map, final K key) {
150 if (map != null) {
151 final Collection<V> col = map.get(key);
152 if (col instanceof Set) {
153 return (Set<V>) col;
154 }
155 return new HashSet<>(col);
156 }
157 return null;
158 }
159
160 /**
161 * Null-safe check if the specified {@code MultiValuedMap} is empty.
162 * <p>
163 * If the provided map is null, returns true.
164 *
165 * @param map the map to check, may be null
166 * @return true if the map is empty or null
167 */
168 public static boolean isEmpty(final MultiValuedMap<?, ?> map) {
169 return map == null || map.isEmpty();
170 }
171
172 /**
173 * Creates a {@link ListValuedMap} with an {@link java.util.ArrayList ArrayList} as
174 * collection class to store the values mapped to a key.
175 *
176 * @param <K> the key type
177 * @param <V> the value type
178 * @return a new {@code ListValuedMap}
179 */
180 public static <K, V> ListValuedMap<K, V> newListValuedHashMap() {
181 return new ArrayListValuedHashMap<>();
182 }
183
184 /**
185 * Creates a {@link SetValuedMap} with an {@link java.util.HashSet HashSet} as
186 * collection class to store the values mapped to a key.
187 *
188 * @param <K> the key type
189 * @param <V> the value type
190 * @return a new {@link SetValuedMap}
191 */
192 public static <K, V> SetValuedMap<K, V> newSetValuedHashMap() {
193 return new HashSetValuedHashMap<>();
194 }
195
196 /**
197 * Returns a {@code TransformedMultiValuedMap} backed by the given map.
198 * <p>
199 * This method returns a new {@code MultiValuedMap} (decorating the
200 * specified map) that will transform any new entries added to it. Existing
201 * entries in the specified map will not be transformed. If you want that
202 * behavior, see {@link TransformedMultiValuedMap#transformedMap}.
203 * <p>
204 * Each object is passed through the transformers as it is added to the Map.
205 * It is important not to use the original map after invoking this method,
206 * as it is a back door for adding untransformed objects.
207 * <p>
208 * If there are any elements already in the map being decorated, they are
209 * NOT transformed.
210 *
211 * @param <K> the key type
212 * @param <V> the value type
213 * @param map the {@link MultiValuedMap} to transform, must not be null, typically empty
214 * @param keyTransformer the transformer for the map keys, null means no transformation
215 * @param valueTransformer the transformer for the map values, null means no transformation
216 * @return a transformed {@code MultiValuedMap} backed by the given map
217 * @throws NullPointerException if map is null
218 */
219 public static <K, V> MultiValuedMap<K, V> transformedMultiValuedMap(final MultiValuedMap<K, V> map,
220 final Transformer<? super K, ? extends K> keyTransformer,
221 final Transformer<? super V, ? extends V> valueTransformer) {
222 return TransformedMultiValuedMap.transformingMap(map, keyTransformer, valueTransformer);
223 }
224
225 /**
226 * Returns an {@code UnmodifiableMultiValuedMap} backed by the given
227 * map.
228 *
229 * @param <K> the key type
230 * @param <V> the value type
231 * @param map the {@link MultiValuedMap} to decorate, must not be null
232 * @return an unmodifiable {@link MultiValuedMap} backed by the provided map
233 * @throws NullPointerException if map is null
234 */
235 public static <K, V> MultiValuedMap<K, V> unmodifiableMultiValuedMap(
236 final MultiValuedMap<? extends K, ? extends V> map) {
237 return UnmodifiableMultiValuedMap.<K, V>unmodifiableMultiValuedMap(map);
238 }
239
240 /**
241 * Don't allow instances.
242 */
243 private MultiMapUtils() {}
244
245 }