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 aClass
to instantiate may be specified, or a factory that returns aCollection
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) $
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
MultiValueMap.ReflectionFactory
Inner class that provides a simple reflection factory.private class
MultiValueMap.Values
Inner class that provides the values view.private class
MultiValueMap.ValuesIterator
Inner class that provides the values iterator.
-
Field Summary
Fields Modifier and Type Field Description private Factory
collectionFactory
The factory for creating value collections.private java.util.Collection
values
The cached values.-
Fields inherited from class org.apache.commons.collections.map.AbstractMapDecorator
map
-
-
Constructor Summary
Constructors Modifier Constructor Description MultiValueMap()
Creates a MultiValueMap based on aHashMap
and storing the multiple values in anArrayList
.protected
MultiValueMap(java.util.Map map, Factory collectionFactory)
Creates a MultiValueMap which decorates the givenmap
and creates the value collections using the suppliedcollectionFactory
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 givenmap
and maps keys to collections of typecollectionClass
.static MultiValueMap
decorate(java.util.Map map, Factory collectionFactory)
Creates a map which decorates the givenmap
and creates the value collections using the suppliedcollectionFactory
.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.boolean
putAll(java.lang.Object key, java.util.Collection values)
Adds a collection of values 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
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
-
-
-
-
Field Detail
-
collectionFactory
private final Factory collectionFactory
The factory for creating value collections.
-
values
private transient java.util.Collection values
The cached values.
-
-
Constructor Detail
-
MultiValueMap
public MultiValueMap()
Creates a MultiValueMap based on aHashMap
and storing the multiple values in anArrayList
.
-
MultiValueMap
protected MultiValueMap(java.util.Map map, Factory collectionFactory)
Creates a MultiValueMap which decorates the givenmap
and creates the value collections using the suppliedcollectionFactory
.- Parameters:
map
- the map to decoratecollectionFactory
- 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 givenmap
and maps keys to collections of typecollectionClass
.- Parameters:
map
- the map to wrapcollectionClass
- the type of the collection class
-
decorate
public static MultiValueMap decorate(java.util.Map map, Factory collectionFactory)
Creates a map which decorates the givenmap
and creates the value collections using the suppliedcollectionFactory
.- Parameters:
map
- the map to decoratecollectionFactory
- the collection factory (must return a Collection object).
-
clear
public void clear()
Clear the map.- Specified by:
clear
in interfacejava.util.Map
- Overrides:
clear
in classAbstractMapDecorator
-
remove
public boolean 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 subsequantget(key)
.
-
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 interfacejava.util.Map
- Specified by:
containsValue
in interfaceMultiMap
- Overrides:
containsValue
in classAbstractMapDecorator
- 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 interfacejava.util.Map
- Specified by:
put
in interfaceMultiMap
- Overrides:
put
in classAbstractMapDecorator
- Parameters:
key
- the key to store againstvalue
- 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 usingputAll(Object,Collection)
.- Specified by:
putAll
in interfacejava.util.Map
- Overrides:
putAll
in classAbstractMapDecorator
- 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 interfacejava.util.Map
- Specified by:
values
in interfaceMultiMap
- Overrides:
values
in classAbstractMapDecorator
- 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 ofget(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 againstvalues
- 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
-
-