org.apache.commons.collections4

Interface MultiValuedMap<K,V>

All Known Subinterfaces:

ListValuedMap<K,V>, SetValuedMap<K,V>

All Known Implementing Classes:

AbstractListValuedMap, AbstractMultiValuedMap, AbstractMultiValuedMapDecorator, AbstractSetValuedMap, ArrayListValuedHashMap, HashSetValuedHashMap, TransformedMultiValuedMap, UnmodifiableMultiValuedMap

public interface MultiValuedMap<K,V>

Defines a map that holds a collection of values against each key.

A MultiValuedMap 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:

 MultiValuedMap<K, String> map = new MultiValuedHashMap<K, String>();
 map.put(key, "A");
 map.put(key, "B");
 map.put(key, "C");
 Collection<String> coll = map.get(key);
 

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

Since:

4.1

Method Summary

Modifier and Type	Method and Description
java.util.Map<K,java.util.Collection<V>>	asMap() Returns a view of this multi-valued map as a Map from each distinct key to the non-empty collection of that key's associated values.
void	clear() Removes all of the mappings from this map (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsMapping(java.lang.Object key, java.lang.Object value) Checks whether the map contains a mapping for the specified key and value.
boolean	containsValue(java.lang.Object value) Checks whether the map contains at least one mapping for the specified value.
java.util.Collection<java.util.Map.Entry<K,V>>	entries() Returns a Collection view of the mappings contained in this multi-valued map.
java.util.Collection<V>	get(K key) Returns a view collection of the values associated with the specified key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
MultiSet<K>	keys() Returns a MultiSet view of the keys contained in this multi-valued map.
java.util.Set<K>	keySet() Returns a Set view of the keys contained in this multi-valued map.
MapIterator<K,V>	mapIterator() Obtains a MapIterator over this multi-valued map.
boolean	put(K key, V value) Adds a key-value mapping to this multi-valued map.
boolean	putAll(K key, java.lang.Iterable<? extends V> values) Adds a mapping to the specified key for all values contained in the given Iterable.
boolean	putAll(java.util.Map<? extends K,? extends V> map) Copies all mappings from the specified map to this multi-valued map (optional operation).
boolean	putAll(MultiValuedMap<? extends K,? extends V> map) Copies all mappings from the specified map to this multi-valued map (optional operation).
java.util.Collection<V>	remove(java.lang.Object key) Removes all values associated with the specified key.
boolean	removeMapping(java.lang.Object key, java.lang.Object item) Removes a key-value mapping from the map.
int	size() Gets the total size of the map.
java.util.Collection<V>	values() Gets a Collection view of all values contained in this multi-valued map.

Method Detail

size

int size()

Gets the total size of the map.

Implementations would return the total size of the map which is the count of the values from all keys.

Returns:

the total size of the map

isEmpty

boolean isEmpty()

Returns true if this map contains no key-value mappings.

Returns:

true if this map contains no key-value mappings

containsKey

boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

Throws:

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

containsValue

boolean containsValue(java.lang.Object value)

Checks whether the map contains at least one mapping for the specified value.

Parameters:

value - the value to search for

Returns:

true if the map contains the value

Throws:

java.lang.NullPointerException - if the value is null and null values are not supported by the used collection types (optional)

containsMapping

boolean containsMapping(java.lang.Object key,
                        java.lang.Object value)

Checks whether the map contains a mapping for the specified key and value.

Parameters:

key - the key to search for

value - the value to search for

Returns:

true if the map contains the value

get

java.util.Collection<V> get(K key)

Returns a view collection of the values associated with the specified key.

This method will return an empty collection if containsKey(Object) returns false. Changes to the returned collection will update the underlying MultiValuedMap and vice-versa.

Parameters:

key - the key to retrieve

Returns:

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

Throws:

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

put

boolean put(K key,
            V value)

Adds a key-value mapping to this multi-valued map.

Unlike a normal Map the previous value is not replaced. Instead the new value is added to the collection stored against the key. Depending on the collection type used, duplicate key-value mappings may be allowed.

The method will return true if the size of the multi-valued map has been increased because of this operation.

Parameters:

key - the key to store against

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

Returns:

true if the map changed as a result of this put operation, or false if the map already contained the key-value mapping and the collection type does not allow duplicate values, e.g. when using a Set

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this multi-valued map, e.g. if it is unmodifiable

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

java.lang.IllegalArgumentException - if some aspect of the specified key or value prevents it from being stored in this multi-valued map

putAll

boolean putAll(K key,
               java.lang.Iterable<? extends V> values)

Adds a mapping to the specified key for all values contained in the given Iterable.

Parameters:

key - the key to store against

values - the values to add to the collection at the key, may not be null

Returns:

true if the map changed as a result of this operation

Throws:

java.lang.NullPointerException - if the specified iterable is null, or if this map does not permit null keys or values, and the specified key or values contain null (optional)

putAll

boolean putAll(java.util.Map<? extends K,? extends V> map)

Copies all mappings from the specified map to this multi-valued map (optional operation).

The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map.

The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Parameters:

map - mappings to be stored in this map, may not be null

Returns:

true if the map changed as a result of this operation

Throws:

java.lang.UnsupportedOperationException - if the putAll operation is not supported by this map

java.lang.NullPointerException - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values (optional)

java.lang.IllegalArgumentException - if some property of a key or value in the specified map prevents it from being stored in this map

putAll

boolean putAll(MultiValuedMap<? extends K,? extends V> map)

Copies all mappings from the specified map to this multi-valued map (optional operation).

The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map.

The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Parameters:

map - mappings to be stored in this map, may not be null

Returns:

true if the map changed as a result of this operation

Throws:

java.lang.UnsupportedOperationException - if the putAll operation is not supported by this map

java.lang.NullPointerException - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values (optional)

java.lang.IllegalArgumentException - if some property of a key or value in the specified map prevents it from being stored in this map

remove

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

Removes all values associated with the specified key.

The returned collection may be modifiable, but updates will not be propagated to this multi-valued map. In case no mapping was stored for the specified key, an empty, unmodifiable collection will be returned.

Parameters:

key - the key to remove values from

Returns:

the values that were removed

Throws:

java.lang.UnsupportedOperationException - if the map is unmodifiable

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

removeMapping

boolean removeMapping(java.lang.Object key,
                      java.lang.Object item)

Removes a key-value mapping from the 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 an empty collection from a subsequent get(Object).

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.NullPointerException - if the key or value is null and null is invalid (optional)

clear

void clear()

Removes all of the mappings from this map (optional operation).

The map will be empty after this call returns.

Throws:

java.lang.UnsupportedOperationException - if the map is unmodifiable

entries

java.util.Collection<java.util.Map.Entry<K,V>> entries()

Returns a Collection view of the mappings contained in this multi-valued map.

The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa.

Returns:

a set view of the mappings contained in this map

keys

MultiSet<K> keys()

Returns a MultiSet view of the keys contained in this multi-valued map.

The MultiSet.getCount(Object) method of the returned multiset will give the same result a calling get(Object).size() for the same key.

This multiset is backed by the map, so any changes in the map are reflected in the multiset.

Returns:

a multiset view of the keys contained in this map

keySet

java.util.Set<K> keySet()

Returns a Set view of the keys contained in this multi-valued map.

The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.

If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the result of the iteration is undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns:

a set view of the keys contained in this map

values

java.util.Collection<V> values()

Gets a Collection view of all values contained in this multi-valued map.

Implementations typically return a collection containing the combination of values from all keys.

Returns:

a collection view of the values contained in this multi-valued map

asMap

java.util.Map<K,java.util.Collection<V>> asMap()

Returns a view of this multi-valued map as a Map from each distinct key to the non-empty collection of that key's associated values.

Note that this.asMap().get(k) is equivalent to this.get(k) only when k is a key contained in the multi-valued map; otherwise it returns null as opposed to an empty collection.

Changes to the returned map or the collections that serve as its values will update the underlying multi-valued map, and vice versa. The map does not support put or putAll, nor do its entries support setValue.

Returns:

a map view of the mappings in this multi-valued map

mapIterator

MapIterator<K,V> mapIterator()

Obtains a MapIterator over this multi-valued map.

A map iterator is an efficient way of iterating over maps. There is no need to access the entries collection or use Map.Entry objects.

Returns:

a map iterator