org.apache.commons.collections4

## Class MultiMapUtils

- java.lang.Object
- - org.apache.commons.collections4.MultiMapUtils

-     public class MultiMapUtils
      extends Object

  Provides utility methods and decorators for `MultiValuedMap` instances.

  It contains various type safe and null safe methods. Additionally, it provides the following decorators:

  - `unmodifiableMultiValuedMap(MultiValuedMap)`
  - `transformedMultiValuedMap(MultiValuedMap, Transformer, Transformer)`
  Since:
    4.1
  Version:
    $Id: MultiMapUtils.java 1715302 2015-11-19 23:08:01Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static MultiValuedMap` | `EMPTY_MULTI_VALUED_MAP` An empty `UnmodifiableMultiValuedMap`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K,V> MultiValuedMap<K,V>` | `emptyIfNull(MultiValuedMap<K,V> map)` Returns an immutable empty `MultiValuedMap` if the argument is `null`, or the argument itself otherwise.
    `static <K,V> MultiValuedMap<K,V>` | `emptyMultiValuedMap()` Returns immutable EMPTY_MULTI_VALUED_MAP with generic type safety.
    `static <K,V> Collection<V>` | `getCollection(MultiValuedMap<K,V> map, K key)` Gets a Collection from `MultiValuedMap` in a null-safe manner.
    `static <K,V> Bag<V>` | `getValuesAsBag(MultiValuedMap<K,V> map, K key)` Gets a Bag from `MultiValuedMap` in a null-safe manner.
    `static <K,V> List<V>` | `getValuesAsList(MultiValuedMap<K,V> map, K key)` Gets a List from `MultiValuedMap` in a null-safe manner.
    `static <K,V> Set<V>` | `getValuesAsSet(MultiValuedMap<K,V> map, K key)` Gets a Set from `MultiValuedMap` in a null-safe manner.
    `static boolean` | `isEmpty(MultiValuedMap<?,?> map)` Null-safe check if the specified `MultiValuedMap` is empty.
    `static <K,V> ListValuedMap<K,V>` | `newListValuedHashMap()` Creates a `ListValuedMap` with an `ArrayList` as collection class to store the values mapped to a key.
    `static <K,V> SetValuedMap<K,V>` | `newSetValuedHashMap()` Creates a `SetValuedMap` with an `HashSet` as collection class to store the values mapped to a key.
    `static <K,V> MultiValuedMap<K,V>` | `transformedMultiValuedMap(MultiValuedMap<K,V> map, Transformer<? super K,? extends K> keyTransformer, Transformer<? super V,? extends V> valueTransformer)` Returns a `TransformedMultiValuedMap` backed by the given map.
    `static <K,V> MultiValuedMap<K,V>` | `unmodifiableMultiValuedMap(MultiValuedMap<? extends K,? extends V> map)` Returns an `UnmodifiableMultiValuedMap` backed by the given map.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_MULTI_VALUED_MAP

          public static final MultiValuedMap EMPTY_MULTI_VALUED_MAP

      An empty `UnmodifiableMultiValuedMap`.

  - ### Method Detail

    - #### emptyMultiValuedMap

          public static <K,V> MultiValuedMap<K,V> emptyMultiValuedMap()

      Returns immutable EMPTY_MULTI_VALUED_MAP with generic type safety.
      Type Parameters:
        `K` - the type of key in the map
        `V` - the type of value in the map
      Returns:
        immutable and empty `MultiValuedMap`

    - #### emptyIfNull

          public static <K,V> MultiValuedMap<K,V> emptyIfNull(MultiValuedMap<K,V> map)

      Returns an immutable empty `MultiValuedMap` if the argument is `null`, or the argument itself otherwise.
      Type Parameters:
        `K` - the type of key in the map
        `V` - the type of value in the map
      Parameters:
        `map` - the map, may be null
      Returns:
        an empty `MultiValuedMap` if the argument is null

    - #### isEmpty

          public static boolean isEmpty(MultiValuedMap<?,?> map)

      Null-safe check if the specified `MultiValuedMap` is empty.

      If the provided map is null, returns true.

      Parameters:
        `map` - the map to check, may be null
      Returns:
        true if the map is empty or null

    - #### getCollection

          public static <K,V> Collection<V> getCollection(MultiValuedMap<K,V> map,
                                          K key)

      Gets a Collection from `MultiValuedMap` in a null-safe manner.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to use
        `key` - the key to look up
      Returns:
        the Collection in the `MultiValuedMap`, or null if input map is null

    - #### getValuesAsList

          public static <K,V> List<V> getValuesAsList(MultiValuedMap<K,V> map,
                                      K key)

      Gets a List from `MultiValuedMap` in a null-safe manner.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to use
        `key` - the key to look up
      Returns:
        the Collection in the `MultiValuedMap` as List, or null if input map is null

    - #### getValuesAsSet

          public static <K,V> Set<V> getValuesAsSet(MultiValuedMap<K,V> map,
                                    K key)

      Gets a Set from `MultiValuedMap` in a null-safe manner.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to use
        `key` - the key to look up
      Returns:
        the Collection in the `MultiValuedMap` as Set, or null if input map is null

    - #### getValuesAsBag

          public static <K,V> Bag<V> getValuesAsBag(MultiValuedMap<K,V> map,
                                    K key)

      Gets a Bag from `MultiValuedMap` in a null-safe manner.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to use
        `key` - the key to look up
      Returns:
        the Collection in the `MultiValuedMap` as Bag, or null if input map is null

    - #### newListValuedHashMap

          public static <K,V> ListValuedMap<K,V> newListValuedHashMap()

      Creates a `ListValuedMap` with an `ArrayList` as collection class to store the values mapped to a key.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a new `ListValuedMap`

    - #### newSetValuedHashMap

          public static <K,V> SetValuedMap<K,V> newSetValuedHashMap()

      Creates a `SetValuedMap` with an `HashSet` as collection class to store the values mapped to a key.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a new `SetValuedMap`

    - #### unmodifiableMultiValuedMap

          public static <K,V> MultiValuedMap<K,V> unmodifiableMultiValuedMap(MultiValuedMap<? extends K,? extends V> map)

      Returns an `UnmodifiableMultiValuedMap` backed by the given map.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to decorate, must not be null
      Returns:
        an unmodifiable `MultiValuedMap` backed by the provided map
      Throws:
        `NullPointerException` - if map is null

    - #### transformedMultiValuedMap

          public static <K,V> MultiValuedMap<K,V> transformedMultiValuedMap(MultiValuedMap<K,V> map,
                                                            Transformer<? super K,? extends K> keyTransformer,
                                                            Transformer<? super V,? extends V> valueTransformer)

      Returns a `TransformedMultiValuedMap` backed by the given map.

      This method returns a new `MultiValuedMap` (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behaviour, see `TransformedMultiValuedMap.transformedMap(org.apache.commons.collections4.MultiValuedMap<K, V>, org.apache.commons.collections4.Transformer<? super K, ? extends K>, org.apache.commons.collections4.Transformer<? super V, ? extends V>)`.

      Each object is passed through the transformers as it is added to the Map. It is important not to use the original map after invoking this method, as it is a back door for adding untransformed objects.

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

      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `map` - the `MultiValuedMap` to transform, must not be null, typically empty
        `keyTransformer` - the transformer for the map keys, null means no transformation
        `valueTransformer` - the transformer for the map values, null means no transformation
      Returns:
        a transformed `MultiValuedMap` backed by the given map
      Throws:
        `NullPointerException` - if map is null

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.