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.map; 18 19 import java.io.IOException; 20 import java.io.ObjectInputStream; 21 import java.io.ObjectOutputStream; 22 import java.io.Serializable; 23 import java.util.Map; 24 25 import org.apache.commons.collections4.Transformer; 26 27 /** 28 * Decorates another {@code Map} to transform objects that are added. 29 * <p> 30 * The Map put methods and Map.Entry setValue method are affected by this class. 31 * Thus objects must be removed or searched for using their transformed form. 32 * For example, if the transformation converts Strings to Integers, you must 33 * use the Integer form to remove objects. 34 * </p> 35 * <p> 36 * <strong>Note that TransformedMap is not synchronized and is not thread-safe.</strong> 37 * If you wish to use this map from multiple threads concurrently, you must use 38 * appropriate synchronization. The simplest approach is to wrap this map 39 * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 40 * exceptions when accessed by concurrent threads without synchronization. 41 * </p> 42 * <p> 43 * This class is Serializable from Commons Collections 3.1. 44 * </p> 45 * 46 * @param <K> the type of the keys in this map 47 * @param <V> the type of the values in this map 48 * 49 * @see org.apache.commons.collections4.splitmap.TransformedSplitMap 50 * @since 3.0 51 */ 52 public class TransformedMap<K, V> 53 extends AbstractInputCheckedMapDecorator<K, V> 54 implements Serializable { 55 56 /** Serialization version */ 57 private static final long serialVersionUID = 7023152376788900464L; 58 59 /** 60 * Factory method to create a transforming map that will transform 61 * existing contents of the specified map. 62 * <p> 63 * If there are any elements already in the map being decorated, they 64 * will be transformed by this method. 65 * Contrast this with {@link #transformingMap(Map, Transformer, Transformer)}. 66 * 67 * @param <K> the key type 68 * @param <V> the value type 69 * @param map the map to decorate, must not be null 70 * @param keyTransformer the transformer to use for key conversion, null means no transformation 71 * @param valueTransformer the transformer to use for value conversion, null means no transformation 72 * @return a new transformed map 73 * @throws NullPointerException if map is null 74 * @since 4.0 75 */ 76 public static <K, V> TransformedMap<K, V> transformedMap(final Map<K, V> map, 77 final Transformer<? super K, ? extends K> keyTransformer, 78 final Transformer<? super V, ? extends V> valueTransformer) { 79 final TransformedMap<K, V> decorated = new TransformedMap<>(map, keyTransformer, valueTransformer); 80 if (!map.isEmpty()) { 81 final Map<K, V> transformed = decorated.transformMap(map); 82 decorated.clear(); 83 decorated.decorated().putAll(transformed); // avoids double transformation 84 } 85 return decorated; 86 } 87 /** 88 * Factory method to create a transforming map. 89 * <p> 90 * If there are any elements already in the map being decorated, they 91 * are NOT transformed. 92 * Contrast this with {@link #transformedMap(Map, Transformer, Transformer)}. 93 * 94 * @param <K> the key type 95 * @param <V> the value type 96 * @param map the map to decorate, must not be null 97 * @param keyTransformer the transformer to use for key conversion, null means no transformation 98 * @param valueTransformer the transformer to use for value conversion, null means no transformation 99 * @return a new transformed map 100 * @throws NullPointerException if map is null 101 * @since 4.0 102 */ 103 public static <K, V> TransformedMap<K, V> transformingMap(final Map<K, V> map, 104 final Transformer<? super K, ? extends K> keyTransformer, 105 final Transformer<? super V, ? extends V> valueTransformer) { 106 return new TransformedMap<>(map, keyTransformer, valueTransformer); 107 } 108 109 /** The transformer to use for the key */ 110 protected final Transformer<? super K, ? extends K> keyTransformer; 111 112 /** The transformer to use for the value */ 113 protected final Transformer<? super V, ? extends V> valueTransformer; 114 115 /** 116 * Constructor that wraps (not copies). 117 * <p> 118 * If there are any elements already in the collection being decorated, they 119 * are NOT transformed. 120 * 121 * @param map the map to decorate, must not be null 122 * @param keyTransformer the transformer to use for key conversion, null means no conversion 123 * @param valueTransformer the transformer to use for value conversion, null means no conversion 124 * @throws NullPointerException if map is null 125 */ 126 protected TransformedMap(final Map<K, V> map, final Transformer<? super K, ? extends K> keyTransformer, 127 final Transformer<? super V, ? extends V> valueTransformer) { 128 super(map); 129 this.keyTransformer = keyTransformer; 130 this.valueTransformer = valueTransformer; 131 } 132 133 /** 134 * Override to transform the value when using {@code setValue}. 135 * 136 * @param value the value to transform 137 * @return the transformed value 138 * @since 3.1 139 */ 140 @Override 141 protected V checkSetValue(final V value) { 142 return valueTransformer.transform(value); 143 } 144 145 /** 146 * Override to only return true when there is a value transformer. 147 * 148 * @return true if a value transformer is in use 149 * @since 3.1 150 */ 151 @Override 152 protected boolean isSetValueChecking() { 153 return valueTransformer != null; 154 } 155 156 @Override 157 public V put(K key, V value) { 158 key = transformKey(key); 159 value = transformValue(value); 160 return decorated().put(key, value); 161 } 162 163 @Override 164 public void putAll(Map<? extends K, ? extends V> mapToCopy) { 165 mapToCopy = transformMap(mapToCopy); 166 decorated().putAll(mapToCopy); 167 } 168 169 /** 170 * Read the map in using a custom routine. 171 * 172 * @param in the input stream 173 * @throws IOException if an error occurs while reading from the stream 174 * @throws ClassNotFoundException if an object read from the stream can not be loaded 175 * @since 3.1 176 */ 177 @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect 178 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { 179 in.defaultReadObject(); 180 map = (Map<K, V>) in.readObject(); // (1) 181 } 182 183 /** 184 * Transforms a key. 185 * <p> 186 * The transformer itself may throw an exception if necessary. 187 * 188 * @param object the object to transform 189 * @return the transformed object 190 */ 191 protected K transformKey(final K object) { 192 if (keyTransformer == null) { 193 return object; 194 } 195 return keyTransformer.transform(object); 196 } 197 198 /** 199 * Transforms a map. 200 * <p> 201 * The transformer itself may throw an exception if necessary. 202 * 203 * @param map the map to transform 204 * @return the transformed object 205 */ 206 @SuppressWarnings("unchecked") 207 protected Map<K, V> transformMap(final Map<? extends K, ? extends V> map) { 208 if (map.isEmpty()) { 209 return (Map<K, V>) map; 210 } 211 final Map<K, V> result = new LinkedMap<>(map.size()); 212 213 for (final Map.Entry<? extends K, ? extends V> entry : map.entrySet()) { 214 result.put(transformKey(entry.getKey()), transformValue(entry.getValue())); 215 } 216 return result; 217 } 218 219 /** 220 * Transforms a value. 221 * <p> 222 * The transformer itself may throw an exception if necessary. 223 * 224 * @param object the object to transform 225 * @return the transformed object 226 */ 227 protected V transformValue(final V object) { 228 if (valueTransformer == null) { 229 return object; 230 } 231 return valueTransformer.transform(object); 232 } 233 234 /** 235 * Write the map out using a custom routine. 236 * 237 * @param out the output stream 238 * @throws IOException if an error occurs while writing to the stream 239 * @since 3.1 240 */ 241 private void writeObject(final ObjectOutputStream out) throws IOException { 242 out.defaultWriteObject(); 243 out.writeObject(map); 244 } 245 246 }