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>

- All Implemented Interfaces:
    Serializable, Map<K,Object>, Get<K,Object>, IterableGet<K,Object>, IterableMap<K,Object>, MultiMap<K,V>, Put<K,Object>

      public class MultiValueMap<K,V>
      extends AbstractMapDecorator<K,Object>
      implements MultiMap<K,V>, Serializable

  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
  Version:
    $Id: MultiValueMap.java 1542763 2013-11-17 17:10:33Z tn $
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `MultiValueMap()` 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)` Creates a MultiValueMap which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.

  - ### Method Summary

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

      `get, remove, size`

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

      `containsKey, equals, hashCode, isEmpty, keySet`

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

      `mapIterator`

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

      `containsKey, isEmpty, keySet`

- - ### Constructor Detail

    - #### MultiValueMap

          public MultiValueMap()

      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)

      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 Detail

    - #### multiValueMap

          public static <K,V> MultiValueMap<K,V> multiValueMap(Map<K,? super Collection<V>> map)

      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

    - #### multiValueMap

          public static <K,V,C extends Collection<V>> MultiValueMap<K,V> multiValueMap(Map<K,? super C> map,
                                                                       Class<C> collectionClass)

      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)

      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

    - #### clear

          public void clear()

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

    - #### removeMapping

          public boolean removeMapping(Object key,
                              Object value)

      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

    - #### containsValue

          public boolean containsValue(Object value)

      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 `Map<K,Object>`
      Specified by:
        `containsValue` in interface `Get<K,Object>`
      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)`

    - #### put

          public Object put(K key,
                   Object value)

      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,Object>`
      Specified by:
        `put` in interface `MultiMap<K,V>`
      Specified by:
        `put` in interface `Put<K,Object>`
      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 void putAll(Map<? extends K,?> map)

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

    - #### entrySet

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

      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 `Map<K,Object>`
      Specified by:
        `entrySet` in interface `Get<K,Object>`
      Overrides:
        `entrySet` in class `AbstractMapDecorator<K,Object>`
      See Also:
        `iterator()`

    - #### values

          public Collection<Object> values()

      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 `Map<K,Object>`
      Specified by:
        `values` in interface `Get<K,Object>`
      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()`

    - #### containsValue

          public boolean containsValue(Object key,
                              Object value)

      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

    - #### getCollection

          public Collection<V> getCollection(Object key)

      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

    - #### size

          public int size(Object key)

      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

    - #### putAll

          public boolean putAll(K key,
                       Collection<V> values)

      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

    - #### iterator

          public Iterator<V> iterator(Object key)

      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

    - #### iterator

          public Iterator<Map.Entry<K,V>> iterator()

      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

    - #### totalSize

          public int totalSize()

      Gets the total size of the map by counting all the values.
      Returns:
        the total size of the map counting all values

    - #### createCollection

          protected Collection<V> createCollection(int size)

      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

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