ch.javasoft.util.map
Interface MultiValueMap<K,V>

All Known Subinterfaces:

IntIntMultiValueMap

All Known Implementing Classes:

AbstractMultiValueMap, AbstractMutableMultiValueMap, DefaultIntIntMultiValueMap, DefaultMultiValueMap, JoinedMultiValueMap, SingleValueMap

public interface MultiValueMap<K,V>

MultiValueMap is a mapping of one key to multiple values. Multiple here means zero to many values. This interface is implemented by mutable and immutable mappings. Immutable mappings throw an UnsupportedOperationException at mutating methods.

This class is similar to Map, but manages multiple values for the same key.

Method Summary

boolean	add(K key, V value) Adds the given value to the multi value map
boolean	addAll(K key, Collection<? extends V> values) Adds the given values to the multi value map
boolean	addAll(K key, V... values) Adds the given values to the multi value map
boolean	addAll(Map<? extends K,? extends V> map) Adds the key/value map entries of the given map to this multi value map
boolean	addAll(MultiValueMap<? extends K,? extends V> mapping) Adds the key/value-collection entries of the given mapping to this key collection
boolean	addAllNested(Map<? extends K,? extends Collection<? extends V>> map) Adds the key/value-collection entries of the given map to this key collection
Map<K,? extends Collection<V>>	asCollectionMap() Returns a map with keys and collections of values.
Map<K,V>	asSingleValueMap() Returns a map with keys and the first value associated with that key.
boolean	clear() Removes all entries from this mapping
boolean	contains(Object key) Returns true if the value collection is non-empty
boolean	contains(Object key, V value) Returns true if the value collection contains at least one occurrence of the given value
int	count(Object key) Returns the number of values in the value collection
Collection<V>	get(Object key) Returns a collection for all values belonging to the specified key, or an empty collection if no such key collection exists yet.
V	getFirst(Object key) Returns the first value of the value collection, or null if no such value exists
MultiValueMap<V,K>	invert() Returns an inverted mapping, where the key can be asked knowing the value.
boolean	isEmpty() Returns true if this map is empty
Set<K>	keySet() Returns a set containing all keys.
int	keySize() Returns the number of keys contained in this mapping
boolean	remove(Object key) Returns all values belonging to this key, i.e.
boolean	remove(Object key, V value) Returns a single value of the value collection, if it exists
Iterable<V>	values() Returns an iterable for all values in this mapping.
int	valueSize() Returns the number of values contained in this mapping

Method Detail

add

boolean add(K key,
            V value)

Adds the given value to the multi value map

Parameters:

key - the key which identifies the value collection

value - the value to add

Returns:

true if this map has changed, which is usually the case. If sets are used as key collections, however, the method could also return false if the given value already existed.

Throws:

UnsupportedOperationException - if this is an immutable map

addAll

boolean addAll(K key,
               V... values)

Adds the given values to the multi value map

Parameters:

key - the key which identifies the value collection

values - the values to add

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

addAll

boolean addAll(Map<? extends K,? extends V> map)

Adds the key/value map entries of the given map to this multi value map

Parameters:

map - the map containing key/value-collection entries to add

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

addAll

boolean addAll(K key,
               Collection<? extends V> values)

Adds the given values to the multi value map

Parameters:

key - the key which identifies the value collection

values - the values to add

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

addAll

boolean addAll(MultiValueMap<? extends K,? extends V> mapping)

Adds the key/value-collection entries of the given mapping to this key collection

Parameters:

mapping - the mapping containing key/value-collection entries to add

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

addAllNested

boolean addAllNested(Map<? extends K,? extends Collection<? extends V>> map)

Adds the key/value-collection entries of the given map to this key collection

Parameters:

map - the map containing key/value-collection entries to add

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

remove

boolean remove(Object key)

Returns all values belonging to this key, i.e. the value collection is cleared

Parameters:

key - the key which identifies the value collection

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

remove

boolean remove(Object key,
               V value)

Returns a single value of the value collection, if it exists

Parameters:

key - the key which identifies the value collection

value - the value to remove

Returns:

true if this map has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

clear

boolean clear()

Removes all entries from this mapping

Returns:

true if this mapping has changed as a consequence of this operation

Throws:

UnsupportedOperationException - if this is an immutable map

get

Collection<V> get(Object key)

Returns a collection for all values belonging to the specified key, or an empty collection if no such key collection exists yet. For existing keys, the returned collection is non-empty.

Parameters:

key - the key which identifies the value collection

Returns:

the value collection for the given key, never null, and non-empty for existing keys

getFirst

V getFirst(Object key)

Returns the first value of the value collection, or null if no such value exists

Parameters:

key - the key which identifies the value collection

Returns:

the first value of the value collection, or null if no such value exists

count

int count(Object key)

Returns the number of values in the value collection

Parameters:

key - the key which identifies the value collection

Returns:

the number of values in the value collection

contains

boolean contains(Object key)

Returns true if the value collection is non-empty

Parameters:

key - the key which identifies the value collection

Returns:

true if at least one value exists in the value collection

contains

boolean contains(Object key,
                 V value)

Returns true if the value collection contains at least one occurrence of the given value

Parameters:

key - the key which identifies the value collection

value - the value to look for

Returns:

true if at least one such value exists in the value collection

keySet

Set<K> keySet()

Returns a set containing all keys. Each value collection associated with the returned keys is non-empty

Returns:

the set of keys identifying non-empty value collections

values

Iterable<V> values()

Returns an iterable for all values in this mapping.

Returns:

an iterator for all values contained in this mapping

asSingleValueMap

Map<K,V> asSingleValueMap()

Returns a map with keys and the first value associated with that key.

Changing the returned map might or might not affect this multi value map, depending on the implementation.

Returns:

a map with key and first associated value

invert

MultiValueMap<V,K> invert()

Returns an inverted mapping, where the key can be asked knowing the value.

Changing the returned map might or might not affect this multi value map, depending on the implementation.

Returns:

the inverted value-key mapping

asCollectionMap

Map<K,? extends Collection<V>> asCollectionMap()

Returns a map with keys and collections of values. All collections in the map are non-empty.

Changing the returned map might or might not affect this multi value map, depending on the implementation.

Returns:

a map with key/collection-of-value entries

keySize

int keySize()

Returns the number of keys contained in this mapping

valueSize

int valueSize()

Returns the number of values contained in this mapping

Returns:

the total number of values

isEmpty

boolean isEmpty()

Returns true if this map is empty

Returns:

true if this map is empty