Iterate over a Guava Multimap

1. Overview

In this article, we will look at one of Map implementations from Google Guava library – Multimap. It is a collection that maps keys to values, similar to java.util.Map, but in which each key may be associated with multiple values.

2. Dependency

First, let’s add the Guava dependency to our pom.xml:

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>33.3.0-jre</version>
</dependency>

The latest version can be found here.

3. Multimap Implementation

In the case of Guava Multimap, if we add two values for the same key, the second value will not override the first value. Instead, we will have two values in the resulting map. Let’s look at a test case:

String key = "a-key";
Multimap<String, String> map = ArrayListMultimap.create();
map.put(key, "firstValue");
map.put(key, "secondValue");
assertEquals(2, map.size());

Printing the map‘s content will output:

{a-key=[firstValue, secondValue]}

When we get values by key “a-key” we get Collection<String> that contains “firstValue” and “secondValue” as a result:

Collection<String> values = map.get(key);

Printing values will output:

[firstValue, secondValue]

4. Iterate Over a Multimap

Typically, the Multimap class provides several built-in methods that we can use to iterate over its content. So, let’s go down the rabbit hole and take a close look at each option.

Before we dive into the nitty-gritty details, let’s create and populate a Multimap with data:

Multimap<String, String> multiMap = ArrayListMultimap.create();
multiMap.putAll("key1", List.of("value1", "value11", "value111"));
multiMap.putAll("key2", List.of("value2", "value22", "value222"));
multiMap.putAll("key3", List.of("value3", "value33", "value333"));

4.1. Using entries()

Let’s start with the easiest solution, which involves using the entries() method. As the name implies, it returns a view collection of all key-value pairs contained in the given Multimap.

So, let’s see it in action:

static void iterateUsingEntries(Multimap<String, String> multiMap) {
    multiMap.entries()
      .forEach(entry -> LOGGER.info("{} => {}", entry.getKey(), entry.getValue()));
}

Executing the method will output:

key1 => value1
key1 => value11
key1 => value111
key2 => value2
key2 => value22
key2 => value222
key3 => value3
key3 => value33
key3 => value333

Here, we used the forEach() method to iterate through the extracted entries. Each entry denotes a Map.Entry instance and holds the key-value pair information.

4.2. Using asMap()

Alternatively, we can use the asMap() method to achieve the same outcome. This method returns a Map view of the specified Multimap:

static void iterateUsingAsMap(Multimap<String, String> multiMap) {
    multiMap.asMap()
      .entrySet()
      .forEach(entry -> LOGGER.info("{} => {}", entry.getKey(), entry.getValue()));
}

Here’s the output:

key1 => [value1, value11, value111]
key2 => [value2, value22, value222]
key3 => [value3, value33, value333]

As we can see, we used the entrySet() method to extract the Set of entries from the returned Map. Then, we iterated through them using the forEach() method.

4.3. Using keySet()

The keySet() method is another option to consider if we want to iterate only through the keys. It returns all the distinct keys contained in a particular Multimap as a Set:

static void iterateUsingKeySet(Multimap<String, String> multiMap) {
    multiMap.keySet()
      .forEach(LOGGER::info);
}

The above method will print:

key1
key2
key3

As we see above, we used a method reference instead of a lambda expression to display the extracted keys.

4.4. Using keys()

Similarly, we can use the keys() method to achieve the same objective. This method returns a view collection containing the key from each key-value pair:

static void iterateUsingKeys(Multimap<String, String> multiMap) {
    multiMap.keys()
      .forEach(LOGGER::info);
}

Unlike keySet(), which returns distinct keys, this method displays a key for each value. With that being said, it prints each key three times:

key1
key1
key1
key2
key2
key2
key3
key3
key3

In a nutshell, keys() returns a Multiset instance unlike keySet() which returns a Set. The key difference is that Multiset accepts duplicate elements.

4.5. Using values()

Lastly, Multimap provides the values() method to get a collection containing the values of the specified Multimap:

static void iterateUsingValues(Multimap<String, String> multiMap) {
    multiMap.values()
      .forEach(LOGGER::info);
}

The method will log the values of each key:

value1
value11
value111
value2
value22
value222
value3
value33
value333

We should note that updating the returned collection updates the underlying Multimap too, and vice versa. However, it’s not possible to add new elements to the collection.

5. Compared to the Standard Map

Standard map from java.util package doesn’t give us the ability to assign multiple values to the same key. Let’s consider a simple case when we put() two values into a Map using the same key:

String key = "a-key";
Map<String, String> map = new LinkedHashMap<>();
map.put(key, "firstValue");
map.put(key, "secondValue");
assertEquals(1, map.size());

The resulting map has only one element (“secondValue”), because of a second put() operation that overrides the first value. Should we want to achieve the same behavior as with Guava’s Multimap, we would need to create a Map that has a List<String> as a value type:

String key = "a-key";
Map<String, List<String>> map = new LinkedHashMap<>();
List<String> values = map.get(key);
if(values == null) {
    values = new LinkedList<>();
    values.add("firstValue");
    values.add("secondValue");
 }
map.put(key, values);
assertEquals(1, map.size());

Obviously, it is not very convenient to use and if we have such need in our code then Guava’s Multimap could be a better choice than java.util.Map.

One thing to notice here is that, although we have a list that has two elements in it, size() method returns 1. In Multimap, size() returns an actual number of values stored in a Map, but keySet().size() returns the number of distinct keys.

6. Pros of Multimap

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

• 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 (in Map<String, Collection<V>>, even if we remove all values from the collection, we still keep an empty Collection as a value, and this is unnecessary memory overhead)
• The total entry values count is available as size()
• Multimap comes with multiple ready-to-use methods that make the iteration logic easy and practical

7. Conclusion

In this article, we learned how and when to use Guava Multimap. We compared it to standard java.util.Map and saw pros of Guava Multimap. Along the way, we explored different ways of iterating over a given Multimap.

All these examples and code snippets can be found available over on GitHub.