Top Description Methods
org.apache.commons.collections4

public Interface MultiMap<K, V>

extends IterableMap<K, Object>
Known Direct Implementers
org.apache.commons.collections4.map.MultiValueMap
Annotations
@Deprecated
Type Parameters
<K>
the type of the keys in this map
<V>
the type of the values in this map
Imports
java.util.Collection

Deprecated

since 4.1, use MultiValuedMap instead

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

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the map contains the value
containsValue(Object
the value to search for
value)

Redeclares java.util.Map.containsValue, org.apache.commons.collections4.Get.containsValue.

Checks whether the map contains the value specified.
public Object

Returns:

the Collection of values, implementations should return null for no mapping, but may return an empty collection
get(Object
the key to retrieve
key)

Redeclares java.util.Map.get, org.apache.commons.collections4.Get.get.

Gets the collection of values associated with the specified key.
public Object

Returns:

typically the value added if the map changed and null if the map did not change
put(K
the key to store against
key, Object
the value to add to the collection at the key
value)

Redeclares java.util.Map.put, org.apache.commons.collections4.Put.put.

Adds the value to the collection associated with the specified key.
public Object

Returns:

the Collection of values removed, implementations should return null for no mapping found, but may return an empty collection
remove(Object
the key to remove values from
key)

Redeclares java.util.Map.remove, org.apache.commons.collections4.Get.remove.

Removes all values associated with the specified key.
public boolean

Returns:

true if the mapping was removed, false otherwise
removeMapping(K
the key to remove from
key, V
the item to remove
item)

Removes a specific value from map.

public int

Returns:

the number of key-collection mappings in this map
size()

Redeclares java.util.Map.size, org.apache.commons.collections4.Get.size.

Gets the number of keys in this map.
public Collection<Object>

Returns:

a collection view of the values contained in this map
values()

Redeclares java.util.Map.values, org.apache.commons.collections4.Get.values.

Gets a collection containing all the values in the map.

Method Detail

containsValueback to summary
public boolean containsValue(Object value)

Redeclares java.util.Map.containsValue, org.apache.commons.collections4.Get.containsValue.

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.

Parameters
value:Object

the value to search for

Returns:boolean

true if the map contains the value

Annotations
@Override
Exceptions
ClassCastException:
if the value is of an invalid type
NullPointerException:
if the value is null and null value are invalid
getback to summary
public Object get(Object key)

Redeclares java.util.Map.get, org.apache.commons.collections4.Get.get.

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.

Parameters
key:Object

the key to retrieve

Returns:Object

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

Annotations
@Override
Exceptions
ClassCastException:
if the key is of an invalid type
NullPointerException:
if the key is null and null keys are invalid
putback to summary
public Object put(K key, Object value)

Redeclares java.util.Map.put, org.apache.commons.collections4.Put.put.

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.

Parameters
key:K

the key to store against

value:Object

the value to add to the collection at the key

Returns:Object

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

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the map is unmodifiable
ClassCastException:
if the key or value is of an invalid type
NullPointerException:
if the key or value is null and null is invalid
IllegalArgumentException:
if the key or value is invalid
removeback to summary
public Object remove(Object key)

Redeclares java.util.Map.remove, org.apache.commons.collections4.Get.remove.

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.

Parameters
key:Object

the key to remove values from

Returns:Object

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

Annotations
@Override
Exceptions
UnsupportedOperationException:
if the map is unmodifiable
ClassCastException:
if the key is of an invalid type
NullPointerException:
if the key is null and null keys are invalid
removeMappingback to summary
public boolean removeMapping(K key, V item)

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:K

the key to remove from

item:V

the item to remove

Returns:boolean

true if the mapping was removed, false otherwise

Exceptions
UnsupportedOperationException:
if the map is unmodifiable
ClassCastException:
if the key or value is of an invalid type
NullPointerException:
if the key or value is null and null is invalid
Since
4.0 (signature in previous releases: V remove(K, V))
sizeback to summary
public int size()

Redeclares java.util.Map.size, org.apache.commons.collections4.Get.size.

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.

Returns:int

the number of key-collection mappings in this map

Annotations
@Override
valuesback to summary
public Collection<Object> values()

Redeclares java.util.Map.values, org.apache.commons.collections4.Get.values.

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.

Returns:Collection<Object>

a collection view of the values contained in this map

Annotations
@Override