org.apache.commons.collections4

Interface MultiMap<K,V>

All Superinterfaces:

Get<K,java.lang.Object>, IterableGet<K,java.lang.Object>, IterableMap<K,java.lang.Object>, java.util.Map<K,java.lang.Object>, Put<K,java.lang.Object>

All Known Implementing Classes:

MultiValueMap

Deprecated.

since 4.1, use MultiValuedMap instead

@Deprecated
public interface MultiMap<K,V>
extends IterableMap<K,java.lang.Object>

Defines a map that holds a collection of values against each 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.

For example:

 MultiMap mhm = new MultiValueMap();
 mhm.put(key, "A");
 mhm.put(key, "B");
 mhm.put(key, "C");
 Collection coll = (Collection) mhm.get(key);

coll will be a collection containing "A", "B", "C".

NOTE: Additional methods were added to this interface in Commons Collections 3.1. These were added solely for documentation purposes and do not change the interface as they were defined in the superinterface Map anyway.

Since:

2.0

Nested Class Summary

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

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

Method Summary

Modifier and Type	Method and Description
boolean	containsValue(java.lang.Object value) Deprecated. Checks whether the map contains the value specified.
java.lang.Object	get(java.lang.Object key) Deprecated. Gets the collection of values associated with the specified key.
java.lang.Object	put(K key, java.lang.Object value) Deprecated. Adds the value to the collection associated with the specified key.
java.lang.Object	remove(java.lang.Object key) Deprecated. Removes all values associated with the specified key.
boolean	removeMapping(K key, V item) Deprecated. Removes a specific value from map.
int	size() Deprecated. Gets the number of keys in this map.
java.util.Collection<java.lang.Object>	values() Deprecated. Gets a collection containing all the values in the map.

Methods inherited from interface java.util.Map

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

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

clear, putAll

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

mapIterator

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

containsKey, entrySet, isEmpty, keySet

Method Detail

removeMapping

boolean removeMapping(K key,
                      V item)

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, implementations typically return null from a subsequent get(Object), however they may choose to return an empty collection.

Parameters:

key - the key to remove from

item - the item to remove

Returns:

true if the mapping was removed, false otherwise

Throws:

java.lang.UnsupportedOperationException - if the map is unmodifiable

java.lang.ClassCastException - if the key or value is of an invalid type

java.lang.NullPointerException - if the key or value is null and null is invalid

Since:

4.0 (signature in previous releases: V remove(K, V))

size

int size()

Deprecated.

Gets the number of keys in this map.

Implementations typically return only the count of keys in the map This cannot be mandated due to backwards compatibility of this interface.

Specified by:

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

Specified by:

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

Returns:

the number of key-collection mappings in this map

See Also:

Map.size()

get

java.lang.Object get(java.lang.Object key)

Deprecated.

Gets the collection of values associated with the specified key.

The returned value will implement Collection. Implementations are free to declare that they return Collection subclasses such as List or Set.

Implementations typically return null if no values have been mapped to the key, however the implementation may choose to return an empty collection.

Implementations may choose to return a clone of the internal collection.

Specified by:

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

Specified by:

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

Parameters:

key - the key to retrieve

Returns:

the Collection of values, implementations should return null for no mapping, but may return an empty collection

Throws:

java.lang.ClassCastException - if the key is of an invalid type

java.lang.NullPointerException - if the key is null and null keys are invalid

See Also:

Map.get(Object)

containsValue

boolean containsValue(java.lang.Object value)

Deprecated.

Checks whether the map contains the value specified.

Implementations typically check all collections against all keys for the value. This cannot be mandated due to backwards compatibility of this interface.

Specified by:

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

Specified by:

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

Parameters:

value - the value to search for

Returns:

true if the map contains the value

Throws:

java.lang.ClassCastException - if the value is of an invalid type

java.lang.NullPointerException - if the value is null and null value are invalid

See Also:

Map.containsValue(Object)

put

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. The collection may be a List, Set or other collection dependent on implementation.

Specified by:

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

Specified by:

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

Parameters:

key - the key to store against

value - the value to add to the collection at the key

Returns:

typically the value added if the map changed and null if the map did not change

Throws:

java.lang.UnsupportedOperationException - if the map is unmodifiable

java.lang.ClassCastException - if the key or value is of an invalid type

java.lang.NullPointerException - if the key or value is null and null is invalid

java.lang.IllegalArgumentException - if the key or value is invalid

See Also:

Map.put(Object, Object)

remove

java.lang.Object remove(java.lang.Object key)

Deprecated.

Removes all values associated with the specified key.

Implementations typically return null from a subsequent get(Object), however they may choose to return an empty collection.

Specified by:

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

Specified by:

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

Parameters:

key - the key to remove values from

Returns:

the Collection of values removed, implementations should return null for no mapping found, but may return an empty collection

Throws:

java.lang.UnsupportedOperationException - if the map is unmodifiable

java.lang.ClassCastException - if the key is of an invalid type

java.lang.NullPointerException - if the key is null and null keys are invalid

See Also:

Map.remove(Object)

values

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

Deprecated.

Gets a collection containing all the values in the map.

Implementations typically return a collection containing the combination of values from all keys. This cannot be mandated due to backwards compatibility of this interface.

Specified by:

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

Specified by:

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

Returns:

a collection view of the values contained in this map

See Also:

Map.values()