MultiMap in Java Guava

Introduction : A Multimap is a general way to associate keys with arbitrarily many values. Guava’s Multimap framework makes it easy to handle a mapping from keys to multiple values. There are two ways to think of a Multimap conceptually :
1) As a collection of mappings from single keys to single values.

a -> 1
a -> 2
a -> 4
b -> 3
c -> 5

2) As a mapping from unique keys to collections of values.

a -> [1, 2, 4]
b -> [3]
c -> [5] 

Declaration : The declaration of com.google.common.collect.Multimap<K, V> interface is as :

@GwtCompatible
public interface Multimap

Below given is the list of some methods provided by Guava’s Multimap Interface :

Views : Multimap also supports a number of powerful views. Much of the power of the multimap API comes from the view collections it provides. These always reflect the latest state of the multimap itself.

• asMap views any Multimap<K, V> as a Map<K, Collection<V>>. The returned map supports remove, and changes to the returned collections write through, but the map does not support put or putAll.
• entries views the Collection<Map.Entry<K, V>> of all entries in the Multimap. (For a SetMultimap, this is a Set.)
• keySet views the distinct keys in the Multimap as a Set.
• keys views the keys of the Multimap as a Multiset, with multiplicity equal to the number of values associated to that key. Elements can be removed from the Multiset, but not added, changes will write through.
• values() views all the values in the Multimap as a “flattened” Collection<V>, all as one collection. This is similar to Iterables.concat(multimap.asMap().values()), but returns a full Collection instead.

Some other methods provided by Guava’s Multimap Interface are :

Multimap V/s Map : A Multimap<K, V> is not a Map<K, Collection<V>>, though such a map might be used in a Multimap implementation. Below given are the differences :

• Multimap.get(key) always returns a non-null, possibly empty collection. This doesn’t imply that the multimap spends any memory associated with the key, but instead, the returned collection is a view that allows you to add associations with the key if you like.
• If you prefer the more Map-like behavior of returning null for keys that aren’t in the multimap, use the asMap() view to get a Map<K, Collection<V>>.
• Multimap.containsKey(key) is true if and only if there are any elements associated with the specified key. In particular, if a key k was previously associated with one or more values which have since been removed from the multimap, Multimap.containsKey(k) will return false.
• Multimap.entries() returns all entries for all keys in the Multimap. If you want all key-collection entries, use asMap().entrySet().
• Multimap.size() returns the number of entries in the entire multimap, not the number of distinct keys. Use Multimap.keySet().size() instead to get the number of distinct keys.

Implementations : Multimap provides a wide variety of implementations. You can use it in most places you would have used a Map<K, Collection<V>>.

Advantages : Multimaps are commonly used in places where a Map<K, Collection<V>> would otherwise have appeared.

• There is no need to populate an empty collection before adding an entry with put().
• The get() method never returns null, only an empty collection (we do not need to check against null like in Map<String, Collection<V>> test case).
• A key is contained in the Multimap if and only if it maps to at least one value. Any operation that causes a key to has zero associated values, has the effect of removing that key from the Multimap.
• The total entry values count is available as size().

References :
Google Guava