TransformedMap.java

  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;

  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;

  25. import org.apache.commons.collections4.Transformer;

  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.  * @see org.apache.commons.collections4.splitmap.TransformedSplitMap
  49.  * @since 3.0
  50.  */
  51. public class TransformedMap<K, V>
  52.         extends AbstractInputCheckedMapDecorator<K, V>
  53.         implements Serializable {

  55.     /** Serialization version */
  56.     private static final long serialVersionUID = 7023152376788900464L;

  58.     /**
  59.      * Factory method to create a transforming map that will transform
  60.      * existing contents of the specified map.
  61.      * <p>
  62.      * If there are any elements already in the map being decorated, they
  63.      * will be transformed by this method.
  64.      * Contrast this with {@link #transformingMap(Map, Transformer, Transformer)}.
  65.      * </p>
  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.      * </p>
  94.      *
  95.      * @param <K>  the key type
  96.      * @param <V>  the value type
  97.      * @param map  the map to decorate, must not be null
  98.      * @param keyTransformer  the transformer to use for key conversion, null means no transformation
  99.      * @param valueTransformer  the transformer to use for value conversion, null means no transformation
  100.      * @return a new transformed map
  101.      * @throws NullPointerException if map is null
  102.      * @since 4.0
  103.      */
  104.     public static <K, V> TransformedMap<K, V> transformingMap(final Map<K, V> map,
  105.             final Transformer<? super K, ? extends K> keyTransformer,
  106.             final Transformer<? super V, ? extends V> valueTransformer) {
  107.         return new TransformedMap<>(map, keyTransformer, valueTransformer);
  108.     }

  110.     /** The transformer to use for the key */
  111.     protected final Transformer<? super K, ? extends K> keyTransformer;

  113.     /** The transformer to use for the value */
  114.     protected final Transformer<? super V, ? extends V> valueTransformer;

  116.     /**
  117.      * Constructor that wraps (not copies).
  118.      * <p>
  119.      * If there are any elements already in the collection being decorated, they
  120.      * are NOT transformed.
  121.      * </p>
  122.      *
  123.      * @param map  the map to decorate, must not be null
  124.      * @param keyTransformer  the transformer to use for key conversion, null means no conversion
  125.      * @param valueTransformer  the transformer to use for value conversion, null means no conversion
  126.      * @throws NullPointerException if map is null
  127.      */
  128.     protected TransformedMap(final Map<K, V> map, final Transformer<? super K, ? extends K> keyTransformer,
  129.             final Transformer<? super V, ? extends V> valueTransformer) {
  130.         super(map);
  131.         this.keyTransformer = keyTransformer;
  132.         this.valueTransformer = valueTransformer;
  133.     }

  135.     /**
  136.      * Override to transform the value when using {@code setValue}.
  137.      *
  138.      * @param value  the value to transform
  139.      * @return the transformed value
  140.      * @since 3.1
  141.      */
  142.     @Override
  143.     protected V checkSetValue(final V value) {
  144.         return valueTransformer.apply(value);
  145.     }

  147.     /**
  148.      * Override to only return true when there is a value transformer.
  149.      *
  150.      * @return true if a value transformer is in use
  151.      * @since 3.1
  152.      */
  153.     @Override
  154.     protected boolean isSetValueChecking() {
  155.         return valueTransformer != null;
  156.     }

  158.     @Override
  159.     public V put(K key, V value) {
  160.         key = transformKey(key);
  161.         value = transformValue(value);
  162.         return decorated().put(key, value);
  163.     }

  165.     @Override
  166.     public void putAll(Map<? extends K, ? extends V> mapToCopy) {
  167.         mapToCopy = transformMap(mapToCopy);
  168.         decorated().putAll(mapToCopy);
  169.     }

  171.     /**
  172.      * Deserializes the map in using a custom routine.
  173.      *
  174.      * @param in  the input stream
  175.      * @throws IOException if an error occurs while reading from the stream
  176.      * @throws ClassNotFoundException if an object read from the stream cannot be loaded
  177.      * @since 3.1
  178.      */
  179.     @SuppressWarnings("unchecked") // (1) should only fail if input stream is incorrect
  180.     private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
  181.         in.defaultReadObject();
  182.         map = (Map<K, V>) in.readObject(); // (1)
  183.     }

  185.     /**
  186.      * Transforms a key.
  187.      * <p>
  188.      * The transformer itself may throw an exception if necessary.
  189.      *
  190.      * @param object  the object to transform
  191.      * @return the transformed object
  192.      */
  193.     protected K transformKey(final K object) {
  194.         if (keyTransformer == null) {
  195.             return object;
  196.         }
  197.         return keyTransformer.apply(object);
  198.     }

  200.     /**
  201.      * Transforms a map.
  202.      * <p>
  203.      * The transformer itself may throw an exception if necessary.
  204.      * </p>
  205.      *
  206.      * @param map  the map to transform
  207.      * @return the transformed object
  208.      */
  209.     @SuppressWarnings("unchecked")
  210.     protected Map<K, V> transformMap(final Map<? extends K, ? extends V> map) {
  211.         if (map.isEmpty()) {
  212.             return (Map<K, V>) map;
  213.         }
  214.         final Map<K, V> result = new LinkedMap<>(map.size());

  216.         for (final Map.Entry<? extends K, ? extends V> entry : map.entrySet()) {
  217.             result.put(transformKey(entry.getKey()), transformValue(entry.getValue()));
  218.         }
  219.         return result;
  220.     }

  222.     /**
  223.      * Transforms a value.
  224.      * <p>
  225.      * The transformer itself may throw an exception if necessary.
  226.      * </p>
  227.      *
  228.      * @param object  the object to transform
  229.      * @return the transformed object
  230.      */
  231.     protected V transformValue(final V object) {
  232.         if (valueTransformer == null) {
  233.             return object;
  234.         }
  235.         return valueTransformer.apply(object);
  236.     }

  238.     /**
  239.      * Serializes this object to an ObjectOutputStream.
  240.      *
  241.      * @param out the target ObjectOutputStream.
  242.      * @throws IOException thrown when an I/O errors occur writing to the target stream.
  243.      * @since 3.1
  244.      */
  245.     private void writeObject(final ObjectOutputStream out) throws IOException {
  246.         out.defaultWriteObject();
  247.         out.writeObject(map);
  248.     }

  250. }
Created with JaCoCo 0.8.12.202403310830