K
- the type of keys maintained by this multimapV
- the type of mapped values@GwtCompatible public interface Multimap<K,V>
Map
, but which may associate multiple
values with a single key. If you call put(K, V)
twice, with the same key
but different values, the multimap contains mappings from the key to both
values.
The methods get(K)
, keySet()
, keys()
, values()
,
entries()
, and asMap()
return collections that are views of the
multimap. If the multimap is modifiable, updating it can change the contents
of those collections, and updating the collections will change the multimap.
In contrast, replaceValues(K, java.lang.Iterable<? extends V>)
and removeAll(java.lang.Object)
return collections
that are independent of subsequent multimap changes.
Depending on the implementation, a multimap may or may not allow duplicate
key-value pairs. In other words, the multimap contents after adding the same
key and value twice varies between implementations. In multimaps allowing
duplicates, the multimap will contain two mappings, and get
will
return a collection that includes the value twice. In multimaps not
supporting duplicates, the multimap will contain a single mapping from the
key to the value, and get
will return a collection that includes the
value once.
All methods that alter the multimap are optional, and the views returned
by the multimap may or may not be modifiable. When modification isn't
supported, those methods will throw an UnsupportedOperationException
.
Modifier and Type | Method and Description |
---|---|
java.util.Map<K,java.util.Collection<V>> |
asMap()
Returns a map view that associates each key with the corresponding values
in the multimap.
|
void |
clear()
Removes all key-value pairs from the multimap.
|
boolean |
containsEntry(java.lang.Object key,
java.lang.Object value)
Returns
true if the multimap contains the specified key-value pair. |
boolean |
containsKey(java.lang.Object key)
Returns
true if the multimap contains any values for the specified
key. |
boolean |
containsValue(java.lang.Object value)
Returns
true if the multimap contains the specified value for any
key. |
java.util.Collection<java.util.Map.Entry<K,V>> |
entries()
Returns a collection of all key-value pairs.
|
boolean |
equals(java.lang.Object obj)
Compares the specified object with this multimap for equality.
|
java.util.Collection<V> |
get(K key)
Returns a collection view of all values associated with a key.
|
int |
hashCode()
Returns the hash code for this multimap.
|
boolean |
isEmpty()
Returns
true if the multimap contains no key-value pairs. |
Multiset<K> |
keys()
Returns a collection, which may contain duplicates, of all keys.
|
java.util.Set<K> |
keySet()
Returns the set of all keys, each appearing once in the returned set.
|
boolean |
put(K key,
V value)
Stores a key-value pair in the multimap.
|
boolean |
putAll(K key,
java.lang.Iterable<? extends V> values)
Stores a collection of values with the same key.
|
boolean |
putAll(Multimap<? extends K,? extends V> multimap)
Copies all of another multimap's key-value pairs into this multimap.
|
boolean |
remove(java.lang.Object key,
java.lang.Object value)
Removes a key-value pair from the multimap.
|
java.util.Collection<V> |
removeAll(java.lang.Object key)
Removes all values associated with a given key.
|
java.util.Collection<V> |
replaceValues(K key,
java.lang.Iterable<? extends V> values)
Stores a collection of values with the same key, replacing any existing
values for that key.
|
int |
size()
Returns the number of key-value pairs in the multimap.
|
java.util.Collection<V> |
values()
Returns a collection of all values in the multimap.
|
int size()
boolean isEmpty()
true
if the multimap contains no key-value pairs.boolean containsKey(@Nullable java.lang.Object key)
true
if the multimap contains any values for the specified
key.key
- key to search for in multimapboolean containsValue(@Nullable java.lang.Object value)
true
if the multimap contains the specified value for any
key.value
- value to search for in multimapboolean containsEntry(@Nullable java.lang.Object key, @Nullable java.lang.Object value)
true
if the multimap contains the specified key-value pair.key
- key to search for in multimapvalue
- value to search for in multimapboolean put(@Nullable K key, @Nullable V value)
Some multimap implementations allow duplicate key-value pairs, in which
case put
always adds a new key-value pair and increases the
multimap size by 1. Other implementations prohibit duplicates, and storing
a key-value pair that's already in the multimap has no effect.
key
- key to store in the multimapvalue
- value to store in the multimaptrue
if the method increased the size of the multimap, or
false
if the multimap already contained the key-value pair and
doesn't allow duplicatesboolean remove(@Nullable java.lang.Object key, @Nullable java.lang.Object value)
key
- key of entry to remove from the multimapvalue
- value of entry to remove the multimaptrue
if the multimap changedboolean putAll(@Nullable K key, java.lang.Iterable<? extends V> values)
key
- key to store in the multimapvalues
- values to store in the multimaptrue
if the multimap changedboolean putAll(Multimap<? extends K,? extends V> multimap)
multimap.entries()
.multimap
- mappings to store in this multimaptrue
if the multimap changedjava.util.Collection<V> replaceValues(@Nullable K key, java.lang.Iterable<? extends V> values)
key
- key to store in the multimapvalues
- values to store in the multimapjava.util.Collection<V> removeAll(@Nullable java.lang.Object key)
key
- key of entries to remove from the multimapvoid clear()
java.util.Collection<V> get(@Nullable K key)
Changes to the returned collection will update the underlying multimap, and vice versa.
key
- key to search for in multimapjava.util.Set<K> keySet()
Multiset<K> keys()
java.util.Collection<V> values()
java.util.Collection<java.util.Map.Entry<K,V>> entries()
add
or addAll
operations.java.util.Map<K,java.util.Collection<V>> asMap()
setValue()
on its entries, put
, or putAll
.
When passed a key that is present in the map, asMap().get(Object)
has the same behavior as get(K)
, returning a
live collection. When passed a key that is not present, however, asMap().get(Object)
returns null
instead of an empty collection.
boolean equals(@Nullable java.lang.Object obj)
asMap()
,
are also equal.
In general, two multimaps with identical key-value mappings may or may
not be equal, depending on the implementation. For example, two
SetMultimap
instances with the same key-value mappings are equal,
but equality of two ListMultimap
instances depends on the ordering
of the values for each key.
A non-empty SetMultimap
cannot be equal to a non-empty
ListMultimap
, since their asMap()
views contain unequal
collections as values. However, any two empty multimaps are equal, because
they both have empty asMap()
views.
equals
in class java.lang.Object
int hashCode()
The hash code of a multimap is defined as the hash code of the map view,
as returned by asMap()
.
hashCode
in class java.lang.Object