org.apache.commons.collections4.map

Class MultiValueMap<K,V>

java.lang.Object

org.apache.commons.collections4.map.AbstractIterableMap<K,V>

org.apache.commons.collections4.map.AbstractMapDecorator<K,java.lang.Object>

org.apache.commons.collections4.map.MultiValueMap<K,V>

All Implemented Interfaces:

java.io.Serializable, java.util.Map<K,java.lang.Object>, Get<K,java.lang.Object>, IterableGet<K,java.lang.Object>, IterableMap<K,java.lang.Object>, MultiMap<K,V>, Put<K,java.lang.Object>

Deprecated.

since 4.1, use MultiValuedMap instead

@Deprecated
public class MultiValueMap<K,V>
extends AbstractMapDecorator<K,java.lang.Object>
implements MultiMap<K,V>, java.io.Serializable

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:

3.2

See Also:

Serialized Form

Nested Class Summary

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

java.util.Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
MultiValueMap() Deprecated. Creates a MultiValueMap based on a HashMap and storing the multiple values in an ArrayList.

Method Summary

Modifier and Type	Method and Description
void	clear() Deprecated. Clear the map.
boolean	containsValue(java.lang.Object value) Deprecated. Checks whether the map contains the value specified.
boolean	containsValue(java.lang.Object key, java.lang.Object value) Deprecated. Checks whether the collection at the specified key contains the value.
java.util.Set<java.util.Map.Entry<K,java.lang.Object>>	entrySet() Deprecated.
java.util.Collection<V>	getCollection(java.lang.Object key) Deprecated. Gets the collection mapped to the specified key.
java.util.Iterator<java.util.Map.Entry<K,V>>	iterator() Deprecated. Gets an iterator for all mappings stored in this MultiValueMap.
java.util.Iterator<V>	iterator(java.lang.Object key) Deprecated. Gets an iterator for the collection mapped to the specified key.
static <K,V,C extends java.util.Collection<V>> MultiValueMap<K,V>	multiValueMap(java.util.Map<K,? super C> map, java.lang.Class<C> collectionClass) Deprecated. Creates a map which decorates the given map and maps keys to collections of type collectionClass.
static <K,V,C extends java.util.Collection<V>> MultiValueMap<K,V>	multiValueMap(java.util.Map<K,? super C> map, Factory<C> collectionFactory) Deprecated. Creates a map which decorates the given map and creates the value collections using the supplied collectionFactory.
static <K,V> MultiValueMap<K,V>	multiValueMap(java.util.Map<K,? super java.util.Collection<V>> map) Deprecated. Creates a map which wraps the given map and maps keys to ArrayLists.
java.lang.Object	put(K key, java.lang.Object value) Deprecated. Adds the value to the collection associated with the specified key.
boolean	putAll(K key, java.util.Collection<V> values) Deprecated. Adds a collection of values to the collection associated with the specified key.
void	putAll(java.util.Map<? extends K,?> map) Deprecated. Override superclass to ensure that MultiMap instances are correctly handled.
boolean	removeMapping(java.lang.Object key, java.lang.Object value) Deprecated. Removes a specific value from map.
int	size(java.lang.Object key) Deprecated. Gets the size of the collection mapped to the specified key.
int	totalSize() Deprecated. Gets the total size of the map by counting all the values.
java.util.Collection<java.lang.Object>	values() Deprecated. Gets a collection containing all the values in the map.

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

containsKey, equals, get, hashCode, isEmpty, keySet, remove, size, toString

Methods inherited from class org.apache.commons.collections4.map.AbstractIterableMap

mapIterator

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

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

get, remove, size

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, containsKey, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, putIfAbsent, remove, replace, replace, replaceAll

Methods inherited from interface org.apache.commons.collections4.IterableGet

mapIterator

Methods inherited from interface org.apache.commons.collections4.Get

containsKey, isEmpty, keySet

Constructor Detail

MultiValueMap

public MultiValueMap()

Deprecated.

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

Method Detail

multiValueMap

public static <K,V> MultiValueMap<K,V> multiValueMap(java.util.Map<K,? super java.util.Collection<V>> map)

Deprecated.

Creates a map which wraps the given map and maps keys to ArrayLists.

Type Parameters:

K - the key type

V - the value type

Parameters:

map - the map to wrap

Returns:

a new multi-value map

Since:

4.0

multiValueMap

public static <K,V,C extends java.util.Collection<V>> MultiValueMap<K,V> multiValueMap(java.util.Map<K,? super C> map,
                                                                                       java.lang.Class<C> collectionClass)

Deprecated.

Creates a map which decorates the given map and maps keys to collections of type collectionClass.

Type Parameters:

K - the key type

V - the value type

C - the collection class type

Parameters:

map - the map to wrap

collectionClass - the type of the collection class

Returns:

a new multi-value map

Since:

4.0

multiValueMap

public static <K,V,C extends java.util.Collection<V>> MultiValueMap<K,V> multiValueMap(java.util.Map<K,? super C> map,
                                                                                       Factory<C> collectionFactory)

Deprecated.

Creates a map which decorates the given map and creates the value collections using the supplied collectionFactory.

Type Parameters:

K - the key type

V - the value type

C - the collection class type

Parameters:

map - the map to decorate

collectionFactory - the collection factory (must return a Collection object).

Returns:

a new multi-value map

Since:

4.0

clear

public void clear()

Deprecated.

Clear the map.

Specified by:

clear in interface java.util.Map<K,java.lang.Object>

Specified by:

clear in interface Put<K,java.lang.Object>

Overrides:

clear in class AbstractMapDecorator<K,java.lang.Object>

See Also:

Map.clear()

removeMapping

public boolean removeMapping(java.lang.Object key,
                             java.lang.Object value)

Deprecated.

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 subsequent get(key).

Specified by:

removeMapping in interface MultiMap<K,V>

Parameters:

key - the key to remove from

value - the value to remove

Returns:

true if the mapping was removed, false otherwise

containsValue

public boolean containsValue(java.lang.Object value)

Deprecated.

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<K,java.lang.Object>

Specified by:

containsValue in interface Get<K,java.lang.Object>

Specified by:

containsValue in interface MultiMap<K,V>

Overrides:

containsValue in class AbstractMapDecorator<K,java.lang.Object>

Parameters:

value - the value to search for

Returns:

true if the map contains the value

See Also:

Map.containsValue(Object)

put

public java.lang.Object put(K key,
                            java.lang.Object value)

Deprecated.

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<K,java.lang.Object>

Specified by:

put in interface MultiMap<K,V>

Specified by:

put in interface Put<K,java.lang.Object>

Overrides:

put in class AbstractMapDecorator<K,java.lang.Object>

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

See Also:

Map.put(Object, Object)

putAll

public void putAll(java.util.Map<? extends K,?> map)

Deprecated.

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<K,java.lang.Object>

Specified by:

putAll in interface Put<K,java.lang.Object>

Overrides:

putAll in class AbstractMapDecorator<K,java.lang.Object>

Parameters:

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

See Also:

Map.putAll(Map)

entrySet

public java.util.Set<java.util.Map.Entry<K,java.lang.Object>> entrySet()

Deprecated.

NOTE: the returned Entry objects will contain as value a Collection of all values that are mapped to the given key. To get a "flattened" version of all mappings contained in this map, use iterator().

Specified by:

entrySet in interface java.util.Map<K,java.lang.Object>

Specified by:

entrySet in interface Get<K,java.lang.Object>

Overrides:

entrySet in class AbstractMapDecorator<K,java.lang.Object>

See Also:

iterator()

values

public java.util.Collection<java.lang.Object> values()

Deprecated.

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<K,java.lang.Object>

Specified by:

values in interface Get<K,java.lang.Object>

Specified by:

values in interface MultiMap<K,V>

Overrides:

values in class AbstractMapDecorator<K,java.lang.Object>

Returns:

a collection view of the values contained in this map

See Also:

Map.values()

containsValue

public boolean containsValue(java.lang.Object key,
                             java.lang.Object value)

Deprecated.

Checks whether the collection at the specified key contains the value.

Parameters:

key - the key to search for

value - the value to search for

Returns:

true if the map contains the value

getCollection

public java.util.Collection<V> getCollection(java.lang.Object key)

Deprecated.

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)

Deprecated.

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(K key,
                      java.util.Collection<V> values)

Deprecated.

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<V> iterator(java.lang.Object key)

Deprecated.

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

iterator

public java.util.Iterator<java.util.Map.Entry<K,V>> iterator()

Deprecated.

Gets an iterator for all mappings stored in this MultiValueMap.

The iterator will return multiple Entry objects with the same key if there are multiple values mapped to this key.

NOTE: calling Map.Entry.setValue(Object) on any of the returned elements will result in a UnsupportedOperationException.

Returns:

the iterator of all mappings in this map

Since:

4.0

totalSize

public int totalSize()

Deprecated.

Gets the total size of the map by counting all the values.

Returns:

the total size of the map counting all values