## 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:
  java.util.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: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
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
`java.util.Map.Entry`

Field Summary

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

Constructor Summary
`` `MultiValueMap()` Creates a MultiValueMap based on a `HashMap` and storing the multiple values in an `ArrayList`.
`protected` `MultiValueMap(java.util.Map map, Factory collectionFactory)` Creates a MultiValueMap which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.

Method Summary
`void` `clear()` Clear the map.
`boolean` `containsValue(java.lang.Object value)` Checks whether the map contains the value specified.
`boolean` `containsValue(java.lang.Object key, java.lang.Object value)` Checks whether the collection at the specified key contains the value.
`protected java.util.Collection` `createCollection(int size)` Creates a new instance of the map value Collection container using the factory.
`static MultiValueMap` `decorate(java.util.Map map)` Creates a map which wraps the given map and maps keys to ArrayLists.
`static MultiValueMap` `decorate(java.util.Map map, java.lang.Class collectionClass)` Creates a map which decorates the given `map` and maps keys to collections of type `collectionClass`.
`static MultiValueMap` `decorate(java.util.Map map, Factory collectionFactory)` Creates a map which decorates the given `map` and creates the value collections using the supplied `collectionFactory`.
`java.util.Collection` `getCollection(java.lang.Object key)` Gets the collection mapped to the specified key.
`java.util.Iterator` `iterator(java.lang.Object key)` Gets an iterator for the collection mapped to the specified key.
`java.lang.Object` `put(java.lang.Object key, java.lang.Object value)` Adds the value to the collection associated with the specified key.
`void` `putAll(java.util.Map map)` Override superclass to ensure that MultiMap instances are correctly handled.
`boolean` `putAll(java.lang.Object key, java.util.Collection values)` Adds a collection of values to the collection associated with the specified key.
`java.lang.Object` `remove(java.lang.Object key, java.lang.Object value)` Removes a specific value from map.
`int` `size(java.lang.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.
`java.util.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(java.util.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(java.util.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(java.util.Map map,
                                         java.lang.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(java.util.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 `java.util.Map`
  Overrides:
    `clear` in class `AbstractMapDecorator`

### remove

    public java.lang.Object remove(java.lang.Object key,
                                   java.lang.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(java.lang.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 `java.util.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 java.lang.Object put(java.lang.Object key,
                                java.lang.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 `java.util.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(java.util.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 `java.util.Map`
  Overrides:
    `putAll` in class `AbstractMapDecorator`
  Parameters:
    `map` - the map to copy (either a normal or multi map)

### values

    public java.util.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 `java.util.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(java.lang.Object key,
                                 java.lang.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 java.util.Collection getCollection(java.lang.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(java.lang.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(java.lang.Object key,
                          java.util.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 java.util.Iterator iterator(java.lang.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 java.util.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-2008 The Apache Software Foundation. All Rights Reserved.