Package org.apache.commons.collections4.map

# Class MultiValueMap<K,V>

java.lang.Object
org.apache.commons.collections4.map.AbstractIterableMap<K,V>
org.apache.commons.collections4.map.AbstractMapDecorator<K,Object>
org.apache.commons.collections4.map.MultiValueMap<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`, `Map<K,Object>`, `Get<K,Object>`, `IterableGet<K,Object>`, `IterableMap<K,Object>`, `MultiMap<K,V>`, `Put<K,Object>`

@Deprecated public class MultiValueMap<K,V> extends AbstractMapDecorator<K,Object> implements MultiMap<K,V>, Serializable
Deprecated.
since 4.1, use `MultiValuedMap` instead
A MultiValueMap decorates another map, allowing it to have more than one value for a key.

A `MultiMap` is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value will return a Collection, holding all the values put to that key.

This implementation is a decorator, allowing any Map implementation to be used as the base.

In addition, this implementation allows the type of collection used for the values to be controlled. By default, an `ArrayList` is used, however a `Class` to instantiate may be specified, or a factory that returns a `Collection` instance.

Note that MultiValueMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since:
  3.2
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K extends Object,V extends Object>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `MultiValueMap()`
  Deprecated.
  Creates a MultiValueMap based on a `HashMap` and storing the multiple values in an `ArrayList`.
  `protected`
  `MultiValueMap(Map<K,? super C> map, Factory<C> collectionFactory)`
  Deprecated.
  Creates a MultiValueMap which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Deprecated.
  Clear the map.
  `boolean`
  `containsValue(Object value)`
  Deprecated.
  Checks whether the map contains the value specified.
  `boolean`
  `containsValue(Object key, Object value)`
  Deprecated.
  Checks whether the collection at the specified key contains the value.
  `protected Collection<V>`
  `createCollection(int size)`
  Deprecated.
  Creates a new instance of the map value Collection container using the factory.
  `Set<Map.Entry<K,Object>>`
  `entrySet()`
  Deprecated.
  `Collection<V>`
  `getCollection(Object key)`
  Deprecated.
  Gets the collection mapped to the specified key.
  `Iterator<Map.Entry<K,V>>`
  `iterator()`
  Deprecated.
  Gets an iterator for all mappings stored in this `MultiValueMap`.
  `Iterator<V>`
  `iterator(Object key)`
  Deprecated.
  Gets an iterator for the collection mapped to the specified key.
  `static <K, V, C extends Collection<V>>
  MultiValueMap<K,V>`
  `multiValueMap(Map<K,? super C> map, Class<C> collectionClass)`
  Deprecated.
  Creates a map which decorates the given `map` and maps keys to collections of type `collectionClass`.
  `static <K, V, C extends Collection<V>>
  MultiValueMap<K,V>`
  `multiValueMap(Map<K,? super C> map, Factory<C> collectionFactory)`
  Deprecated.
  Creates a map which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
  `static <K, V> MultiValueMap<K,V>`
  `multiValueMap(Map<K,? super Collection<V>> map)`
  Deprecated.
  Creates a map which wraps the given map and maps keys to ArrayLists.
  `Object`
  `put(K key, Object value)`
  Deprecated.
  Adds the value to the collection associated with the specified key.
  `void`
  `putAll(Map<? extends K,?> map)`
  Deprecated.
  Override superclass to ensure that MultiMap instances are correctly handled.
  `boolean`
  `putAll(K key, Collection<V> values)`
  Deprecated.
  Adds a collection of values to the collection associated with the specified key.
  `boolean`
  `removeMapping(Object key, Object value)`
  Deprecated.
  Removes a specific value from map.
  `int`
  `size(Object key)`
  Deprecated.
  Gets the size of the collection mapped to the specified key.
  `int`
  `totalSize()`
  Deprecated.
  Gets the total size of the map by counting all the values.
  `Collection<Object>`
  `values()`
  Deprecated.
  Gets a collection containing all the values in the map.

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractMapDecorator

  `containsKey, decorated, equals, get, hashCode, isEmpty, keySet, remove, size, toString`

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractIterableMap

  `mapIterator`

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

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

  ### Methods inherited from interface org.apache.commons.collections4.Get

  `containsKey, isEmpty, keySet`

  ### Methods inherited from interface org.apache.commons.collections4.IterableGet

  `mapIterator`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, containsKey, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, putIfAbsent, remove, replace, replace, replaceAll`

  ### Methods inherited from interface org.apache.commons.collections4.MultiMap

  `get, remove, size`

- ## Constructor Details

  - ### MultiValueMap

    public MultiValueMap()
    Deprecated.
    Creates a MultiValueMap based on a `HashMap` and storing the multiple values in an `ArrayList`.

  - ### MultiValueMap

    protected MultiValueMap(Map<K,? super C> map, Factory<C> collectionFactory)
    Deprecated.
    Creates a MultiValueMap which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
    Type Parameters:
      `C` - the collection class type
    Parameters:
      `map` - the map to decorate
      `collectionFactory` - the collection factory which must return a Collection instance

- ## Method Details

  - ### multiValueMap

    public static <K, V, C extends Collection<V>> MultiValueMap<K,V> multiValueMap(Map<K,? super C> map, Class<C> collectionClass)
    Deprecated.
    Creates a map which decorates the given `map` and maps keys to collections of type `collectionClass`.
    Type Parameters:
      `K` - the key type
      `V` - the value type
      `C` - the collection class type
    Parameters:
      `map` - the map to wrap
      `collectionClass` - the type of the collection class
    Returns:
      a new multi-value map
    Since:
      4.0

  - ### multiValueMap

    public static <K, V, C extends Collection<V>> MultiValueMap<K,V> multiValueMap(Map<K,? super C> map, Factory<C> collectionFactory)
    Deprecated.
    Creates a map which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
    Type Parameters:
      `K` - the key type
      `V` - the value type
      `C` - the collection class type
    Parameters:
      `map` - the map to decorate
      `collectionFactory` - the collection factory (must return a Collection object).
    Returns:
      a new multi-value map
    Since:
      4.0

  - ### multiValueMap

    public static <K, V> MultiValueMap<K,V> multiValueMap(Map<K,? super Collection<V>> map)
    Deprecated.
    Creates a map which wraps the given map and maps keys to ArrayLists.
    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `map` - the map to wrap
    Returns:
      a new multi-value map
    Since:
      4.0

  - ### clear

    public void clear()
    Deprecated.
    Clear the map.
    Specified by:
      `clear` in interface `Map<K,V>`
    Specified by:
      `clear` in interface `Put<K,V>`
    Overrides:
      `clear` in class `AbstractMapDecorator<K,Object>`
    See Also:
      - `Map.clear()`

  - ### containsValue

    public boolean containsValue(Object value)
    Deprecated.
    Checks whether the map contains the value specified.

    This checks all collections against all keys for the value, and thus could be slow.

    Specified by:
      `containsValue` in interface `Get<K,V>`
    Specified by:
      `containsValue` in interface `Map<K,V>`
    Specified by:
      `containsValue` in interface `MultiMap<K,V>`
    Overrides:
      `containsValue` in class `AbstractMapDecorator<K,Object>`
    Parameters:
      `value` - the value to search for
    Returns:
      true if the map contains the value
    See Also:
      - `Map.containsValue(Object)`

  - ### containsValue

    public boolean containsValue(Object key, Object value)
    Deprecated.
    Checks whether the collection at the specified key contains the value.
    Parameters:
      `key` - the key to search for
      `value` - the value to search for
    Returns:
      true if the map contains the value

  - ### createCollection

    protected Collection<V> createCollection(int size)
    Deprecated.
    Creates a new instance of the map value Collection container using the factory.

    This method can be overridden to perform your own processing instead of using the factory.

    Parameters:
      `size` - the collection size that is about to be added
    Returns:
      the new collection

  - ### entrySet

    public Set<Map.Entry<K,Object>> entrySet()
    Deprecated.

    NOTE: the returned Entry objects will contain as value a `Collection` of all values that are mapped to the given key. To get a "flattened" version of all mappings contained in this map, use `iterator()`.

    Specified by:
      `entrySet` in interface `Get<K,V>`
    Specified by:
      `entrySet` in interface `Map<K,V>`
    Overrides:
      `entrySet` in class `AbstractMapDecorator<K,Object>`
    Returns:
      a set view of the mappings contained in this map
    See Also:
      - `iterator()`

  - ### getCollection

    public Collection<V> getCollection(Object key)
    Deprecated.
    Gets the collection mapped to the specified key. This method is a convenience method to typecast the result of `get(key)`.
    Parameters:
      `key` - the key to retrieve
    Returns:
      the collection mapped to the key, null if no mapping

  - ### iterator

    public Iterator<Map.Entry<K,V>> iterator()
    Deprecated.
    Gets an iterator for all mappings stored in this `MultiValueMap`.

    The iterator will return multiple Entry objects with the same key if there are multiple values mapped to this key.

    NOTE: calling `Map.Entry.setValue(Object)` on any of the returned elements will result in a `UnsupportedOperationException`.

    Returns:
      the iterator of all mappings in this map
    Since:
      4.0

  - ### iterator

    public Iterator<V> iterator(Object key)
    Deprecated.
    Gets an iterator for the collection mapped to the specified key.
    Parameters:
      `key` - the key to get an iterator for
    Returns:
      the iterator of the collection at the key, empty iterator if key not in map

  - ### put

    public Object put(K key, Object value)
    Deprecated.
    Adds the value to the collection associated with the specified key.

    Unlike a normal `Map` the previous value is not replaced. Instead, the new value is added to the collection stored against the key.

    Specified by:
      `put` in interface `Map<K,V>`
    Specified by:
      `put` in interface `MultiMap<K,V>`
    Specified by:
      `put` in interface `Put<K,V>`
    Overrides:
      `put` in class `AbstractMapDecorator<K,Object>`
    Parameters:
      `key` - the key to store against
      `value` - the value to add to the collection at the key
    Returns:
      the value added if the map changed and null if the map did not change
    See Also:
      - `Map.put(Object, Object)`

  - ### putAll

    public boolean putAll(K key, Collection<V> values)
    Deprecated.
    Adds a collection of values to the collection associated with the specified key.
    Parameters:
      `key` - the key to store against
      `values` - the values to add to the collection at the key, null ignored
    Returns:
      true if this map changed

  - ### putAll

    public void putAll(Map<? extends K,?> map)
    Deprecated.
    Override superclass to ensure that MultiMap instances are correctly handled.

    If you call this method with a normal map, each entry is added using `put(Object,Object)`. If you call this method with a multi map, each entry is added using `putAll(Object,Collection)`.

    Specified by:
      `putAll` in interface `Map<K,V>`
    Specified by:
      `putAll` in interface `Put<K,V>`
    Overrides:
      `putAll` in class `AbstractMapDecorator<K,Object>`
    Parameters:
      `map` - the map to copy (either a normal or multi map)
    See Also:
      - `Map.putAll(Map)`

  - ### removeMapping

    public boolean removeMapping(Object key, Object value)
    Deprecated.
    Removes a specific value from map.

    The item is removed from the collection mapped to the specified key. Other values attached to that key are unaffected.

    If the last value for a key is removed, `null` will be returned from a subsequent `get(key)`.

    Specified by:
      `removeMapping` in interface `MultiMap<K,V>`
    Parameters:
      `key` - the key to remove from
      `value` - the value to remove
    Returns:
      `true` if the mapping was removed, `false` otherwise

  - ### size

    public int size(Object key)
    Deprecated.
    Gets the size of the collection mapped to the specified key.
    Parameters:
      `key` - the key to get size for
    Returns:
      the size of the collection at the key, zero if key not in map

  - ### totalSize

    public int totalSize()
    Deprecated.
    Gets the total size of the map by counting all the values.
    Returns:
      the total size of the map counting all values

  - ### values

    public Collection<Object> values()
    Deprecated.
    Gets a collection containing all the values in the map.

    This returns a collection containing the combination of values from all keys.

    Specified by:
      `values` in interface `Get<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Specified by:
      `values` in interface `MultiMap<K,V>`
    Overrides:
      `values` in class `AbstractMapDecorator<K,Object>`
    Returns:
      a collection view of the values contained in this map
    See Also:
      - `Map.values()`