Package org.apache.commons.collections4.multimap

# Class TransformedMultiValuedMap<K,V>

java.lang.Object
org.apache.commons.collections4.multimap.AbstractMultiValuedMapDecorator<K,V>
org.apache.commons.collections4.multimap.TransformedMultiValuedMap<K,V>

Type Parameters:
  `K` - the type of the keys in this map
  `V` - the type of the values in this map

All Implemented Interfaces:
  `Serializable`, `MultiValuedMap<K,V>`

public class TransformedMultiValuedMap<K,V> extends AbstractMultiValuedMapDecorator<K,V>
Decorates another `MultiValuedMap` to transform objects that are added.

This class affects the MultiValuedMap put methods. Thus objects must be removed or searched for using their transformed form. For example, if the transformation converts Strings to Integers, you must use the Integer form to remove objects.

Note that TransformedMultiValuedMap is not synchronized and is not thread-safe.

Since:
  4.1
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `TransformedMultiValuedMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)`
  Constructor that wraps (not copies).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `put(K key, V value)`
  Adds a key-value mapping to this multivalued map.
  `boolean`
  `putAll(Map<? extends K,? extends V> map)`
  Copies all mappings from the specified map to this multivalued map (optional operation).
  `boolean`
  `putAll(K key, Iterable<? extends V> values)`
  Adds a mapping to the specified key for all values contained in the given Iterable.
  `boolean`
  `putAll(MultiValuedMap<? extends K,? extends V> map)`
  Copies all mappings from the specified map to this multivalued map (optional operation).
  `static <K, V> TransformedMultiValuedMap<K,V>`
  `transformedMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)`
  Factory method to create a transforming MultiValuedMap that will transform existing contents of the specified map.
  `static <K, V> TransformedMultiValuedMap<K,V>`
  `transformingMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)`
  Factory method to create a transforming MultiValuedMap.
  `protected K`
  `transformKey(K object)`
  Transforms a key.
  `protected V`
  `transformValue(V object)`
  Transforms a value.

  ### Methods inherited from class org.apache.commons.collections4.multimap.AbstractMultiValuedMapDecorator

  `asMap, clear, containsKey, containsMapping, containsValue, decorated, entries, equals, get, hashCode, isEmpty, keys, keySet, mapIterator, remove, removeMapping, size, toString, values`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### TransformedMultiValuedMap

    protected TransformedMultiValuedMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
    Constructor that wraps (not copies).

    If there are any elements already in the collection being decorated, they are NOT transformed.

    Parameters:
      `map` - the MultiValuedMap to decorate, may not be null
      `keyTransformer` - the transformer to use for key conversion, null means no conversion
      `valueTransformer` - the transformer to use for value conversion, null means no conversion
    Throws:
      `NullPointerException` - if map is null

- ## Method Details

  - ### transformedMap

    public static <K, V> TransformedMultiValuedMap<K,V> transformedMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
    Factory method to create a transforming MultiValuedMap that will transform existing contents of the specified map.

    If there are any elements already in the map being decorated, they will be transformed by this method. Contrast this with `transformingMap(MultiValuedMap, Transformer, Transformer)`.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the MultiValuedMap to decorate, may not be null
      `keyTransformer` - the transformer to use for key conversion, null means no conversion
      `valueTransformer` - the transformer to use for value conversion, null means no conversion
    Returns:
      a new transformed MultiValuedMap
    Throws:
      `NullPointerException` - if map is null

  - ### transformingMap

    public static <K, V> TransformedMultiValuedMap<K,V> transformingMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)
    Factory method to create a transforming MultiValuedMap.

    If there are any elements already in the map being decorated, they are NOT transformed. Contrast this with `transformedMap(MultiValuedMap, Transformer, Transformer)`.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the MultiValuedMap to decorate, may not be null
      `keyTransformer` - the transformer to use for key conversion, null means no conversion
      `valueTransformer` - the transformer to use for value conversion, null means no conversion
    Returns:
      a new transformed MultiValuedMap
    Throws:
      `NullPointerException` - if map is null

  - ### put

    public boolean put(K key, V value)
    Description copied from interface: `MultiValuedMap`
    Adds a key-value mapping to this multivalued map.

    Unlike a normal `Map` the previous value is not replaced. Instead, the new value is added to the collection stored against the key. Depending on the collection type used, duplicate key-value mappings may be allowed.

    The method will return `true` if the size of the multivalued map has been increased because of this operation.

    Specified by:
      `put` in interface `MultiValuedMap<K,V>`
    Overrides:
      `put` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - the key to store against
      `value` - the value to add to the collection at the key
    Returns:
      true if the map changed as a result of this put operation, or false if the map already contained the key-value mapping and the collection type does not allow duplicate values, e.g. when using a Set

  - ### putAll

    public boolean putAll(K key, Iterable<? extends V> values)
    Description copied from interface: `MultiValuedMap`
    Adds a mapping to the specified key for all values contained in the given Iterable.
    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `key` - the key to store against
      `values` - the values to add to the collection at the key, may not be null
    Returns:
      true if the map changed as a result of this operation

  - ### putAll

    public boolean putAll(Map<? extends K,? extends V> map)
    Description copied from interface: `MultiValuedMap`
    Copies all mappings from the specified map to this multivalued map (optional operation).

    The effect of this call is equivalent to that of calling `put(k, v)` on this map once for each mapping from key `k` to value `v` in the specified map.

    The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `map` - mappings to be stored in this map, may not be null
    Returns:
      true if the map changed as a result of this operation

  - ### putAll

    public boolean putAll(MultiValuedMap<? extends K,? extends V> map)
    Description copied from interface: `MultiValuedMap`
    Copies all mappings from the specified map to this multivalued map (optional operation).

    The effect of this call is equivalent to that of calling `put(k, v)` on this map once for each mapping from key `k` to value `v` in the specified map.

    The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

    Specified by:
      `putAll` in interface `MultiValuedMap<K,V>`
    Overrides:
      `putAll` in class `AbstractMultiValuedMapDecorator<K,V>`
    Parameters:
      `map` - mappings to be stored in this map, may not be null
    Returns:
      true if the map changed as a result of this operation

  - ### transformKey

    protected K transformKey(K object)
    Transforms a key.

    The transformer itself may throw an exception if necessary.

    Parameters:
      `object` - the object to transform
    Returns:
      the transformed object

  - ### transformValue

    protected V transformValue(V object)
    Transforms a value.

    The transformer itself may throw an exception if necessary.

    Parameters:
      `object` - the object to transform
    Returns:
      the transformed object