net.innig.collect
Interface MultiMap<K,V>

All Known Implementing Classes:

CompositeMultiMap, HashMultiMap, TreeMultiMap

public interface MultiMap<K,V>

A map which allows multiple values per key. This interface is similar to Map, but while the entries in an ordinary map have unique keys, the entries in a multi-map are unqiue by key/value pair.

The behavior of a multi-map is undefined if its keys are mutable.

As with the standard Java collections classes, instances of MultiMap are unsynchronized. See net.innig.collect.InnigCollections for synchronizedMultiMap() and unmodifiableMultiMap() methods.

The Jakarta Commons Collections package also provides a MultiMap. I like mine a bit better -- instead of extending Map (which ends up breaking the Map contract), it provides a set of methods more particularly tailored to the behavior of a MultiMap. However, the Jakarta Collections are more widely accepted, and are a generally excellent package, so I certainly recommend checking them out!

Maturity: This is a 90% mature API.

Plans: There are no current plans to expand or revise this interface.

Version:

[Development version]

Author:

Paul Cantrell

See Also:

InnigCollections

Nested Class Summary

static interface

MultiMap.Entry<EK,EV> Represents a single key/value pair in the multi-map.

Method Summary

void	clear() Clears all entries.
boolean	containsKey(K key) Returns true if there is at least one mapping for the given key.
boolean	containsValue(V value) Returns true if there is at least one key which maps to the given values.
java.util.Set<MultiMap.Entry<K,V>>	entrySet() Returns the set of key/value pairs in this multi-map.
boolean	equals(java.lang.Object o) Two multi-maps are equal iff they contain the same key/value mappings.
java.util.Set<V>	get(K key) Returns the set of values for a given key.
int	hashCode()
boolean	isEmpty() Returns true if there are no mappings.
java.util.Set<K>	keySet() Returns the set of keys in this multi-map.
boolean	put(K key, V value) Adds a mapping from a key to a value.
boolean	putAll(K key, java.util.Collection<? extends V> values) Adds mappings from a key to several different values.
void	putAll(java.util.Map<? extends K,? extends V> map) Adds all entries from a map to this multi-map.
void	putAll(MultiMap<? extends K,? extends V> multimap) Adds all entries from another multi-map to this one.
boolean	remove(K key, V value) Removes a key/value mapping.
java.util.Set<V>	removeKey(K key) Removes all key/value mappings for a given key.
int	size() Returns the number of key/value mappings in the multi-map.
java.util.Collection<V>	values() Returns the values in this multi-map.

Method Detail

size

int size()

Returns the number of key/value mappings in the multi-map.

isEmpty

boolean isEmpty()

Returns true if there are no mappings.

containsKey

boolean containsKey(K key)

Returns true if there is at least one mapping for the given key.

containsValue

boolean containsValue(V value)

Returns true if there is at least one key which maps to the given values. Note that this method will likely execute in linear time in the number of key/value paris.

get

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

Returns the set of values for a given key.

put

boolean put(K key,
            V value)

Adds a mapping from a key to a value. This does not replace other existing mappings from the same key. However, if the key/value pair is already in the multi-map, it will not be added twice.

Returns:

true if the new key/value pair was not already in the multi-map.

putAll

boolean putAll(K key,
               java.util.Collection<? extends V> values)

Adds mappings from a key to several different values. These values are in addition to any existing mappings for the given key.

Returns:

true if any of the new key/value pairs were not already in the multi-map.

remove

boolean remove(K key,
               V value)

Removes a key/value mapping.

Returns:

true if the key/value pair was in the multi-map.

removeKey

java.util.Set<V> removeKey(K key)

Removes all key/value mappings for a given key.

Returns:

The set of values which were associated with removed key.

putAll

void putAll(MultiMap<? extends K,? extends V> multimap)

Adds all entries from another multi-map to this one.

putAll

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

Adds all entries from a map to this multi-map.

clear

void clear()

Clears all entries.

keySet

java.util.Set<K> keySet()

Returns the set of keys in this multi-map. The returned set is backed by the actual multi-map, and will reflect subsequent changes.

values

java.util.Collection<V> values()

Returns the values in this multi-map. The returned collection is backed by the actual multi-map, and will reflect subsequent changes.

entrySet

java.util.Set<MultiMap.Entry<K,V>> entrySet()

Returns the set of key/value pairs in this multi-map. The returned set is backed by the actual multi-map, and will reflect subsequent changes.

equals

boolean equals(java.lang.Object o)

Two multi-maps are equal iff they contain the same key/value mappings.

Overrides:

equals in class java.lang.Object

hashCode

int hashCode()

Overrides:

hashCode in class java.lang.Object