public class

MultiValueMap

extends AbstractMapDecorator
implements MultiMap
java.lang.Object
   ↳ org.apache.commons.collections.map.AbstractMapDecorator
     ↳ org.apache.commons.collections.map.MultiValueMap

Class Overview

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.

Summary

[Expand]
Inherited Fields
From class org.apache.commons.collections.map.AbstractMapDecorator
Public Constructors
MultiValueMap()
Creates a MultiValueMap based on a HashMap and storing the multiple values in an ArrayList.
Protected Constructors
MultiValueMap(Map map, Factory collectionFactory)
Creates a MultiValueMap which decorates the given map and creates the value collections using the supplied collectionFactory.
Public Methods
void clear()
Clear the map.
boolean containsValue(Object key, Object value)
Checks whether the collection at the specified key contains the value.
boolean containsValue(Object value)
Checks whether the map contains the value specified.
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.
static MultiValueMap decorate(Map map)
Creates a map which wraps the given map and maps keys to ArrayLists.
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.
Protected Methods
Collection createCollection(int size)
Creates a new instance of the map value Collection container using the factory.
[Expand]
Inherited Methods
From class org.apache.commons.collections.map.AbstractMapDecorator
From class java.lang.Object
From interface java.util.Map
From interface org.apache.commons.collections.MultiMap

Public Constructors

public MultiValueMap ()

Creates a MultiValueMap based on a HashMap and storing the multiple values in an ArrayList.

Protected Constructors

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

Public Methods

public void clear ()

Clear the map.

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

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.

Parameters
value the value to search for
Returns
  • true if the map contains the value

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

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).

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

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

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

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.

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

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).

Parameters
map the map to copy (either a normal or multi map)

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

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).

Parameters
key the key to remove from
value the value to remove
Returns
  • the value removed (which was passed in), null if nothing removed

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

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

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.

Returns
  • a collection view of the values contained in this map

Protected Methods

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