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)`
  Deprecated.
  Since 4.6.0, use `getValuesAsMultiSet(MultiValuedMap, Object)` instead.
  `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> MultiSet<V>`
  `getValuesAsMultiSet(MultiValuedMap<K,V> map, K key)`
  Gets a MultiSet 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 <K, V, M extends MultiValuedMap<K, V>>
  M`
  `invert(MultiValuedMap<? extends V,? extends K> input, M output)`
  Inverts the mappings from an input MultiValuedMap by adding entries to an output MultiValuedMap.
  `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

    @Deprecated public static <K, V> Bag<V> getValuesAsBag(MultiValuedMap<K,V> map, K key)
    Deprecated.
    Since 4.6.0, use `getValuesAsMultiSet(MultiValuedMap, Object)` instead.
    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:
      A new Bag containing the values from 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:
      A new List containing the values from the `MultiValuedMap`, or null if input map is null.

  - ### getValuesAsMultiSet

    public static <K, V> MultiSet<V> getValuesAsMultiSet(MultiValuedMap<K,V> map, K key)
    Gets a MultiSet 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:
      A new MultiSet containing the values from the `MultiValuedMap`, or null if input map is null.
    Since:
      4.6.0

  - ### 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:
      A new Set containing the values from the `MultiValuedMap`, or null if input map is null.

  - ### invert

    public static <K, V, M extends MultiValuedMap<K, V>> M invert(MultiValuedMap<? extends V,? extends K> input, M output)
    Inverts the mappings from an input MultiValuedMap by adding entries to an output MultiValuedMap. The input is unchanged.

    Use this method to have complete control of the output MultiValuedMap or when merging several inverse mappings. In simple cases, consider using `MultiValuedMap.inverted()` method.

    Type Parameters:
      `K` - the input value type and output key type.
      `V` - the input key type and output value type.
      `M` - the output MultiValuedMap type where `K` is the key type and `V` is the value type.
    Parameters:
      `input` - The input key-value mappings of type `<V, K>`.
      `output` - The output value-key mappings of type `<K, V>`.
    Returns:
      The updated output MultiValuedMap of type `<K, V>`
    Since:
      4.6.0
    See Also:
      - `MultiValuedMap.inverted()`

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