org.apache.commons.collections.map

## Class MultiValueMap

- java.lang.Object
- - org.apache.commons.collections.map.AbstractMapDecorator
  - - org.apache.commons.collections.map.MultiValueMap

- All Implemented Interfaces:
    Map, MultiMap

      public class MultiValueMap
      extends AbstractMapDecorator
      implements MultiMap

  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:
    Commons Collections 3.2
  Version:
    $Revision: 1713175 $ $Date: 2015-11-07 21:47:04 +0100 (Sat, 07 Nov 2015) $
  Author:
    James Carman, Christopher Berry, James Strachan, Steve Downey, Stephen Colebourne, Julien Buret, Serhiy Yevtushenko

- - ### Nested Class Summary

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

      `Map.Entry`

  - ### Field Summary

    - ### Fields inherited from class org.apache.commons.collections.map.AbstractMapDecorator

      `map`

  - ### 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 map, Factory 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` | `createCollection(int size)` Creates a new instance of the map value Collection container using the factory.
    `static MultiValueMap` | `decorate(Map map)` Creates a map which wraps the given map and maps keys to ArrayLists.
    `static MultiValueMap` | `decorate(Map map, Class collectionClass)` Creates a map which decorates the given `map` and maps keys to collections of type `collectionClass`.
    `static MultiValueMap` | `decorate(Map map, Factory collectionFactory)` Creates a map which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
    `Collection` | `getCollection(Object key)` Gets the collection mapped to the specified key.
    `Iterator` | `iterator(Object key)` Gets an iterator for the collection mapped to the specified key.
    `Object` | `put(Object key, Object value)` Adds the value to the collection associated with the specified key.
    `void` | `putAll(Map map)` Override superclass to ensure that MultiMap instances are correctly handled.
    `boolean` | `putAll(Object key, Collection values)` Adds a collection of values to the collection associated with the specified key.
    `Object` | `remove(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` | `values()` Gets a collection containing all the values in the map.

    - ### Methods inherited from class org.apache.commons.collections.map.AbstractMapDecorator

      `containsKey, entrySet, equals, get, getMap, hashCode, isEmpty, keySet, remove, size, toString`

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

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

    - ### Methods inherited from interface org.apache.commons.collections.MultiMap

      `get, remove, size`

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

      `containsKey, entrySet, equals, hashCode, 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 map,
                       Factory collectionFactory)

      Creates a MultiValueMap which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
      Parameters:
        `map` - the map to decorate
        `collectionFactory` - the collection factory which must return a Collection instance

  - ### Method Detail

    - #### decorate

          public static MultiValueMap decorate(Map map)

      Creates a map which wraps the given map and maps keys to ArrayLists.
      Parameters:
        `map` - the map to wrap

    - #### decorate

          public static MultiValueMap decorate(Map map,
                               Class collectionClass)

      Creates a map which decorates the given `map` and maps keys to collections of type `collectionClass`.
      Parameters:
        `map` - the map to wrap
        `collectionClass` - the type of the collection class

    - #### decorate

          public static MultiValueMap decorate(Map map,
                               Factory collectionFactory)

      Creates a map which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
      Parameters:
        `map` - the map to decorate
        `collectionFactory` - the collection factory (must return a Collection object).

    - #### clear

          public void clear()

      Clear the map.
      Specified by:
        `clear` in interface `Map`
      Overrides:
        `clear` in class `AbstractMapDecorator`

    - #### remove

          public Object remove(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 subsequant `get(key)`.

      Specified by:
        `remove` in interface `MultiMap`
      Parameters:
        `key` - the key to remove from
        `value` - the value to remove
      Returns:
        the value removed (which was passed in), null if nothing removed

    - #### 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`
      Specified by:
        `containsValue` in interface `MultiMap`
      Overrides:
        `containsValue` in class `AbstractMapDecorator`
      Parameters:
        `value` - the value to search for
      Returns:
        true if the map contains the value

    - #### put

          public Object put(Object 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`
      Specified by:
        `put` in interface `MultiMap`
      Overrides:
        `put` in class `AbstractMapDecorator`
      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

    - #### putAll

          public void putAll(Map 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`
      Overrides:
        `putAll` in class `AbstractMapDecorator`
      Parameters:
        `map` - the map to copy (either a normal or multi map)

    - #### values

          public Collection 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`
      Specified by:
        `values` in interface `MultiMap`
      Overrides:
        `values` in class `AbstractMapDecorator`
      Returns:
        a collection view of the values contained in this map

    - #### containsValue

          public boolean containsValue(Object key,
                              Object value)

      Checks whether the collection at the specified key contains the value.
      Parameters:
        `value` - the value to search for
      Returns:
        true if the map contains the value

    - #### getCollection

          public Collection 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(Object key,
                       Collection 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 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

    - #### 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 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–2015 The Apache Software Foundation. All rights reserved.