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<K extends Object,V extends Object>

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

Constructor Summary

Constructors
Modifier	Constructor	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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	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.
`boolean`	`putAll(Object key, Collection values)`	Adds a collection of values to the collection associated with the specified key.
`void`	`putAll(Map map)`	Override superclass to ensure that MultiMap instances are correctly handled.
`Object`	`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`	`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 java.util.Map
compute, computeIfAbsent, computeIfPresent, containsKey, entrySet, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, putIfAbsent, remove, replace, replace, replaceAll

Methods inherited from interface org.apache.commons.collections.MultiMap
get, remove, size

- 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
  - removeMapping
```
public Object 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 subsequant get(key).
    
    Specified by:
    
    removeMapping 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

Class MultiValueMap

Nested Class Summary

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

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

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

Constructor Detail

MultiValueMap

MultiValueMap

Method Detail

decorate

decorate

decorate

clear

removeMapping

containsValue

put

putAll

values

containsValue

getCollection

size

putAll

iterator

totalSize

createCollection