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 classprivate classprivate classprivate final classprivate final classprivate classList decorator that stays in sync with the multimap values for a key and supports rapid random access.private classprivate class(package private) classCollection decorator that stays in sync with the multimap values for a key.(package private) classList decorator that stays in sync with the multimap values for a key.(package private) class(package private) classSet decorator that stays in sync with the multimap values for a key.(package private) classSortedSet 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 longprivate int -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedAbstractMapBasedMultimap(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>> voidclear()Removes all key-value pairs from the multimap, leaving it empty.booleancontainsKey(Object key) Returnstrueif 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.Entryinstances.Returns an iterator across all key-value map entries, used byentries().iterator()andvalues().iterator().(package private) Spliterator<Map.Entry<K, V>> voidforEach(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 withkeyin this multimap, if any.private Collection<V> getOrCreateCollection(K key) private static <E> Iterator<E> iteratorOrListIterator(Collection<E> collection) booleanStores a key-value pair in this multimap.Removes all values associated with the keykey.private voidremoveValuesForKey(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 voidsetMap(Map<K, Collection<V>> map) Used during deserialization only.intsize()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- ifmapis 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
createCollectionshould 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. TheLinkedHashMultimapclass 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:MultimapReturns 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 theMultimapclass documentation for clarification. -
containsKey
Description copied from interface:MultimapReturnstrueif this multimap contains at least one key-value pair with the keykey.- Specified by:
containsKeyin interfaceMultimap<K,V>
-
put
Description copied from interface:MultimapStores a key-value pair in this multimap.Some multimap implementations allow duplicate key-value pairs, in which case
putalways 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
valuesis empty, this is equivalent toremoveAll(key).The returned collection is immutable.
- Specified by:
replaceValuesin interfaceMultimap<K,V> - Overrides:
replaceValuesin 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,
keywill 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:MultimapRemoves all key-value pairs from the multimap, leaving it empty. -
get
Returns a view collection of the values associated withkeyin 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:
createKeySetin 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:
createValuesin classAbstractMultimap<K,V>
-
valueIterator
- Overrides:
valueIteratorin classAbstractMultimap<K,V>
-
valueSpliterator
Spliterator<V> valueSpliterator()- Overrides:
valueSpliteratorin classAbstractMultimap<K,V>
-
createKeys
- Specified by:
createKeysin classAbstractMultimap<K,V>
-
entries
Returns a view collection of all key-value pairs contained in this multimap, asMap.Entryinstances.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:
createEntriesin 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 mostAbstractMapBasedMultimapimplementations.- Specified by:
entryIteratorin classAbstractMultimap<K,V> - Returns:
- an iterator across map entries
-
entrySpliterator
Spliterator<Map.Entry<K,V>> entrySpliterator()- Overrides:
entrySpliteratorin classAbstractMultimap<K,V>
-
forEach
Description copied from interface:MultimapPerforms the given action for all key-value pairs contained in this multimap. If an ordering is specified by theMultimapimplementation, 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:
createAsMapin classAbstractMultimap<K,V>
-