Class AbstractMapBasedMultimap<K,V>
- All Implemented Interfaces:
Multimap<K,
,V> Serializable
- Direct Known Subclasses:
AbstractListMultimap
,AbstractSetMultimap
,Multimaps.CustomMultimap
Multimap
interface. This class represents a multimap as a map
that associates each key with a collection of values. All methods of Multimap
are
supported, including those specified as optional in the interface.
To implement a multimap, a subclass must define the method createCollection()
, which
creates an empty collection of values for a key.
The multimap constructor takes a map that has a single entry for each distinct key. When you
insert a key-value pair with a key that isn't already in the multimap,
AbstractMapBasedMultimap
calls createCollection()
to create the collection of values
for that key. The subclass should not call createCollection()
directly, and a new
instance should be created every time the method is called.
For example, the subclass could pass a TreeMap
during construction, and
createCollection()
could return a TreeSet
, in which case the
multimap's iterators would propagate through the keys and values in sorted order.
Keys and values may be null, as long as the underlying collection classes support null elements.
The collections created by createCollection()
may or may not allow duplicates. If the
collection, such as a Set
, does not support duplicates, an added key-value pair will
replace an existing pair with the same key and value, if such a pair is present. With collections
like List
that allow duplicates, the collection will keep the existing key-value pairs
while adding a new pair.
This class is not threadsafe when any concurrent operations update the multimap, even if the
underlying map and createCollection()
method return threadsafe classes. Concurrent read
operations will work correctly. To allow concurrent update operations, wrap your multimap with a
call to Multimaps.synchronizedMultimap(com.google.common.collect.Multimap<K, V>)
.
For serialization to work, the subclass must specify explicit readObject
and
writeObject
methods.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
private class
private class
private final class
private final class
private class
List decorator that stays in sync with the multimap values for a key and supports rapid random access.private class
private class
(package private) class
Collection decorator that stays in sync with the multimap values for a key.(package private) class
List decorator that stays in sync with the multimap values for a key.(package private) class
(package private) class
Set decorator that stays in sync with the multimap values for a key.(package private) class
SortedSet decorator that stays in sync with the multimap values for a key.Nested classes/interfaces inherited from class com.google.common.collect.AbstractMultimap
AbstractMultimap.Entries, AbstractMultimap.EntrySet, AbstractMultimap.Values
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Map
<K, Collection<V>> private static final long
private int
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
AbstractMapBasedMultimap
(Map<K, Collection<V>> map) Creates a new multimap that uses the provided map. -
Method Summary
Modifier and TypeMethodDescription(package private) Map
<K, Collection<V>> void
clear()
Removes all key-value pairs from the multimap, leaving it empty.boolean
containsKey
(Object key) Returnstrue
if this multimap contains at least one key-value pair with the keykey
.(package private) Map
<K, Collection<V>> (package private) abstract Collection
<V> Creates the collection of values for a single key.(package private) Collection
<V> createCollection
(K key) Creates the collection of values for an explicitly provided key.(package private) Collection
<Map.Entry<K, V>> (package private) final Map
<K, Collection<V>> (package private) Collection
<V> Creates an unmodifiable, empty collection of values.(package private) Collection
<V> entries()
Returns a view collection of all key-value pairs contained in this multimap, asMap.Entry
instances.Returns an iterator across all key-value map entries, used byentries().iterator()
andvalues().iterator()
.(package private) Spliterator
<Map.Entry<K, V>> void
forEach
(BiConsumer<? super K, ? super V> action) Performs the given action for all key-value pairs contained in this multimap.Returns a view collection of the values associated withkey
in this multimap, if any.private Collection
<V> getOrCreateCollection
(K key) private static <E> Iterator
<E> iteratorOrListIterator
(Collection<E> collection) boolean
Stores a key-value pair in this multimap.Removes all values associated with the keykey
.private void
removeValuesForKey
(Object key) Removes all values for the provided key.replaceValues
(K key, Iterable<? extends V> values) Stores a collection of values with the same key, replacing any existing values for that key.(package private) final void
setMap
(Map<K, Collection<V>> map) Used during deserialization only.int
size()
Returns the number of key-value pairs in this multimap.(package private) <E> Collection
<E> unmodifiableCollectionSubclass
(Collection<E> collection) values()
Returns a view collection containing the value from each key-value pair contained in this multimap, without collapsing duplicates (sovalues().size() == size()
).(package private) Spliterator
<V> (package private) Collection
<V> wrapCollection
(K key, Collection<V> collection) Generates a decorated collection that remains consistent with the values in the multimap for the provided key.wrapList
(K key, List<V> list, AbstractMapBasedMultimap<K, V>.WrappedCollection ancestor) Methods inherited from class com.google.common.collect.AbstractMultimap
asMap, containsEntry, containsValue, equals, hashCode, isEmpty, keys, keySet, putAll, putAll, remove, toString
-
Field Details
-
map
-
totalSize
private transient int totalSize -
serialVersionUID
private static final long serialVersionUID- See Also:
-
-
Constructor Details
-
AbstractMapBasedMultimap
Creates a new multimap that uses the provided map.- Parameters:
map
- place to store the mapping from each key to its corresponding values- Throws:
IllegalArgumentException
- ifmap
is not empty
-
-
Method Details
-
setMap
Used during deserialization only. -
createUnmodifiableEmptyCollection
Collection<V> createUnmodifiableEmptyCollection()Creates an unmodifiable, empty collection of values.This is used in
removeAll(java.lang.Object)
on an empty key. -
createCollection
Creates the collection of values for a single key.Collections with weak, soft, or phantom references are not supported. Each call to
createCollection
should create a new instance.The returned collection class determines whether duplicate key-value pairs are allowed.
- Returns:
- an empty collection of values
-
createCollection
Creates the collection of values for an explicitly provided key. By default, it simply callscreateCollection()
, which is the correct behavior for most implementations. TheLinkedHashMultimap
class overrides it.- Parameters:
key
- key to associate with values in the collection- Returns:
- an empty collection of values
-
backingMap
Map<K,Collection<V>> backingMap() -
size
public int size()Description copied from interface:Multimap
Returns the number of key-value pairs in this multimap.Note: this method does not return the number of distinct keys in the multimap, which is given by
keySet().size()
orasMap().size()
. See the opening section of theMultimap
class documentation for clarification. -
containsKey
Description copied from interface:Multimap
Returnstrue
if this multimap contains at least one key-value pair with the keykey
.- Specified by:
containsKey
in interfaceMultimap<K,
V>
-
put
Description copied from interface:Multimap
Stores a key-value pair in this multimap.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. -
getOrCreateCollection
-
replaceValues
Stores a collection of values with the same key, replacing any existing values for that key.If
values
is empty, this is equivalent toremoveAll(key)
.The returned collection is immutable.
- Specified by:
replaceValues
in interfaceMultimap<K,
V> - Overrides:
replaceValues
in classAbstractMultimap<K,
V> - Returns:
- the collection of replaced values, or an empty collection if no values were previously associated with the key. The collection may be modifiable, but updating it will have no effect on the multimap.
-
removeAll
Removes all values associated with the keykey
.Once this method returns,
key
will not be mapped to any values, so it will not appear inMultimap.keySet()
,Multimap.asMap()
, or any other views.The returned collection is immutable.
-
unmodifiableCollectionSubclass
-
clear
public void clear()Description copied from interface:Multimap
Removes all key-value pairs from the multimap, leaving it empty. -
get
Returns a view collection of the values associated withkey
in this multimap, if any. Note that whencontainsKey(key)
is false, this returns an empty collection, notnull
.Changes to the returned collection will update the underlying multimap, and vice versa.
The returned collection is not serializable.
-
wrapCollection
Generates a decorated collection that remains consistent with the values in the multimap for the provided key. Changes to the multimap may alter the returned collection, and vice versa. -
wrapList
final List<V> wrapList(K key, List<V> list, @CheckForNull AbstractMapBasedMultimap<K, V>.WrappedCollection ancestor) -
iteratorOrListIterator
-
createKeySet
- Specified by:
createKeySet
in classAbstractMultimap<K,
V>
-
removeValuesForKey
Removes all values for the provided key. -
values
Returns a view collection containing the value from each key-value pair contained in this multimap, without collapsing duplicates (sovalues().size() == size()
).Changes to the returned collection will update the underlying multimap, and vice versa. However, adding to the returned collection is not possible.
The iterator generated by the returned collection traverses the values for one key, followed by the values of a second key, and so on.
-
createValues
Collection<V> createValues()- Specified by:
createValues
in classAbstractMultimap<K,
V>
-
valueIterator
- Overrides:
valueIterator
in classAbstractMultimap<K,
V>
-
valueSpliterator
Spliterator<V> valueSpliterator()- Overrides:
valueSpliterator
in classAbstractMultimap<K,
V>
-
createKeys
- Specified by:
createKeys
in classAbstractMultimap<K,
V>
-
entries
Returns a view collection of all key-value pairs contained in this multimap, asMap.Entry
instances.Changes to the returned collection or the entries it contains will update the underlying multimap, and vice versa. However, adding to the returned collection is not possible.
The iterator generated by the returned collection traverses the values for one key, followed by the values of a second key, and so on.
Each entry is an immutable snapshot of a key-value mapping in the multimap, taken at the time the entry is returned by a method call to the collection or its iterator.
-
createEntries
Collection<Map.Entry<K,V>> createEntries()- Specified by:
createEntries
in classAbstractMultimap<K,
V>
-
entryIterator
Returns an iterator across all key-value map entries, used byentries().iterator()
andvalues().iterator()
. The default behavior, which traverses the values for one key, the values for a second key, and so on, suffices for mostAbstractMapBasedMultimap
implementations.- Specified by:
entryIterator
in classAbstractMultimap<K,
V> - Returns:
- an iterator across map entries
-
entrySpliterator
Spliterator<Map.Entry<K,V>> entrySpliterator()- Overrides:
entrySpliterator
in classAbstractMultimap<K,
V>
-
forEach
Description copied from interface:Multimap
Performs the given action for all key-value pairs contained in this multimap. If an ordering is specified by theMultimap
implementation, actions will be performed in the order of iteration ofMultimap.entries()
. Exceptions thrown by the action are relayed to the caller.To loop over all keys and their associated value collections, write
Multimaps.asMap(multimap).forEach((key, valueCollection) -> action())
. -
createAsMap
Map<K,Collection<V>> createAsMap()- Specified by:
createAsMap
in classAbstractMultimap<K,
V>
-