View Javadoc
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.multimap;
18  
19  import java.util.Iterator;
20  import java.util.Map;
21  
22  import org.apache.commons.collections4.CollectionUtils;
23  import org.apache.commons.collections4.FluentIterable;
24  import org.apache.commons.collections4.MultiValuedMap;
25  import org.apache.commons.collections4.Transformer;
26  
27  /**
28   * Decorates another <code>MultiValuedMap</code> to transform objects that are added.
29   * <p>
30   * This class affects the MultiValuedMap put methods. Thus objects must be
31   * removed or searched for using their transformed form. For example, if the
32   * transformation converts Strings to Integers, you must use the Integer form to
33   * remove objects.
34   * </p>
35   * <p>
36   * <strong>Note that TransformedMultiValuedMap is not synchronized and is not thread-safe.</strong>
37   * </p>
38   *
39   * @param <K> the type of the keys in this map
40   * @param <V> the type of the values in this map
41   * @since 4.1
42   */
43  public class TransformedMultiValuedMap<K, V> extends AbstractMultiValuedMapDecorator<K, V> {
44  
45      /** Serialization Version */
46      private static final long serialVersionUID = 20150612L;
47  
48      /** The key transformer */
49      private final Transformer<? super K, ? extends K> keyTransformer;
50  
51      /** The value transformer */
52      private final Transformer<? super V, ? extends V> valueTransformer;
53  
54      /**
55       * Factory method to create a transforming MultiValuedMap.
56       * <p>
57       * If there are any elements already in the map being decorated, they are
58       * NOT transformed. Contrast this with
59       * {@link #transformedMap(MultiValuedMap, Transformer, Transformer)}.
60       *
61       * @param <K> the key type
62       * @param <V> the value type
63       * @param map  the MultiValuedMap to decorate, may not be null
64       * @param keyTransformer  the transformer to use for key conversion, null means no conversion
65       * @param valueTransformer  the transformer to use for value conversion, null means no conversion
66       * @return a new transformed MultiValuedMap
67       * @throws NullPointerException if map is null
68       */
69      public static <K, V> TransformedMultiValuedMap<K, V> transformingMap(final MultiValuedMap<K, V> map,
70              final Transformer<? super K, ? extends K> keyTransformer,
71              final Transformer<? super V, ? extends V> valueTransformer) {
72          return new TransformedMultiValuedMap<>(map, keyTransformer, valueTransformer);
73      }
74  
75      /**
76       * Factory method to create a transforming MultiValuedMap that will
77       * transform existing contents of the specified map.
78       * <p>
79       * If there are any elements already in the map being decorated, they will
80       * be transformed by this method. Contrast this with
81       * {@link #transformingMap(MultiValuedMap, Transformer, Transformer)}.
82       *
83       * @param <K> the key type
84       * @param <V> the value type
85       * @param map  the MultiValuedMap to decorate, may not be null
86       * @param keyTransformer  the transformer to use for key conversion, null means no conversion
87       * @param valueTransformer  the transformer to use for value conversion, null means no conversion
88       * @return a new transformed MultiValuedMap
89       * @throws NullPointerException if map is null
90       */
91      public static <K, V> TransformedMultiValuedMap<K, V> transformedMap(final MultiValuedMap<K, V> map,
92              final Transformer<? super K, ? extends K> keyTransformer,
93              final Transformer<? super V, ? extends V> valueTransformer) {
94          final TransformedMultiValuedMap<K, V> decorated =
95                  new TransformedMultiValuedMap<>(map, keyTransformer, valueTransformer);
96          if (!map.isEmpty()) {
97              final MultiValuedMap<K, V> mapCopy = new ArrayListValuedHashMap<>(map);
98              decorated.clear();
99              decorated.putAll(mapCopy);
100         }
101         return decorated;
102     }
103 
104     // -----------------------------------------------------------------------
105     /**
106      * Constructor that wraps (not copies).
107      * <p>
108      * If there are any elements already in the collection being decorated, they
109      * are NOT transformed.
110      *
111      * @param map  the MultiValuedMap to decorate, may not be null
112      * @param keyTransformer  the transformer to use for key conversion, null means no conversion
113      * @param valueTransformer  the transformer to use for value conversion, null means no conversion
114      * @throws NullPointerException if map is null
115      */
116     protected TransformedMultiValuedMap(final MultiValuedMap<K, V> map,
117             final Transformer<? super K, ? extends K> keyTransformer,
118             final Transformer<? super V, ? extends V> valueTransformer) {
119         super(map);
120         this.keyTransformer = keyTransformer;
121         this.valueTransformer = valueTransformer;
122     }
123 
124     /**
125      * Transforms a key.
126      * <p>
127      * The transformer itself may throw an exception if necessary.
128      *
129      * @param object  the object to transform
130      * @return the transformed object
131      */
132     protected K transformKey(final K object) {
133         if (keyTransformer == null) {
134             return object;
135         }
136         return keyTransformer.transform(object);
137     }
138 
139     /**
140      * Transforms a value.
141      * <p>
142      * The transformer itself may throw an exception if necessary.
143      *
144      * @param object  the object to transform
145      * @return the transformed object
146      */
147     protected V transformValue(final V object) {
148         if (valueTransformer == null) {
149             return object;
150         }
151         return valueTransformer.transform(object);
152     }
153 
154     @Override
155     public boolean put(final K key, final V value) {
156         return decorated().put(transformKey(key), transformValue(value));
157     }
158 
159     @Override
160     public boolean putAll(final K key, final Iterable<? extends V> values) {
161         if (values == null) {
162             throw new NullPointerException("Values must not be null.");
163         }
164 
165         final Iterable<V> transformedValues = FluentIterable.of(values).transform(valueTransformer);
166         final Iterator<? extends V> it = transformedValues.iterator();
167         return it.hasNext() && CollectionUtils.addAll(decorated().get(transformKey(key)), it);
168     }
169 
170     @Override
171     public boolean putAll(final Map<? extends K, ? extends V> map) {
172         if (map == null) {
173             throw new NullPointerException("Map must not be null.");
174         }
175         boolean changed = false;
176         for (final Map.Entry<? extends K, ? extends V> entry : map.entrySet()) {
177             changed |= put(entry.getKey(), entry.getValue());
178         }
179         return changed;
180     }
181 
182     @Override
183     public boolean putAll(final MultiValuedMap<? extends K, ? extends V> map) {
184         if (map == null) {
185             throw new NullPointerException("Map must not be null.");
186         }
187         boolean changed = false;
188         for (final Map.Entry<? extends K, ? extends V> entry : map.entries()) {
189             changed |= put(entry.getKey(), entry.getValue());
190         }
191         return changed;
192     }
193 
194 }