Package 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

- ## Field Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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 Details

  - ### EMPTY_MULTI_VALUED_MAP

    public static final MultiValuedMap EMPTY_MULTI_VALUED_MAP
    An empty `UnmodifiableMultiValuedMap`.

- ## Method Details

  - ### 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

  - ### 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`

  - ### 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

  - ### 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

  - ### 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

  - ### 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

  - ### 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`

  - ### 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 behavior, 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

  - ### 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