Handle Duplicate Keys When Producing Map Using Java Stream

1. Overview

When producing a Map using Java Stream, it’s possible to encounter duplicated keys. This can cause issues when adding values to the map, as the previous value associated with the key may be overwritten.

In this tutorial, we’ll discuss handling duplicated keys when generating a Map using the Stream API.

2. Introduction to the Problem

As usual, let’s understand the problem through examples. Let’s say we have a City class:

class City {
    private String name;
    private String locatedIn;

    public City(String name, String locatedIn) {
        this.name = name;
        this.locatedIn = locatedIn;
    }
    
    // Omitted getter methods
    // Omitted the equals() and hashCode() methods
    // ...
}

As the class code above shows, City is a POJO class with two string properties. One is the name of the city. The other gives more information about where the city is located.

Moreover, the class overrides the equals() and hashCode() methods. These two methods check both name and locatedIn properties. To keep it simple, we didn’t put the methods’ implementation in the snippet.

Next, let’s create a list of City instances:

final List<City> CITY_INPUT = Arrays.asList(
  new City("New York City", "USA"),
  new City("Shanghai", "China"),
  new City("Hamburg", "Germany"),
  new City("Paris", "France"),
  new City("Paris", "Texas, USA"));

As the code above shows, we initialize a List<City> from an array to be compatible with the older Java version. The CITY_INPUT list holds five cities. Let’s pay attention to the last two cities we packed into the list:

• new City(“Paris”, “France”) 
• new City(“Paris”, “Texas, USA”) 

Both cities have the same name, “Paris“. However, their different locatedIn values are telling us that the two Paris instances are different cities.

Now, let’s say we want to produce a Map using the cities’ names as the keys from the CITY_INPUT list. Apparently, the two Paris cities will have the same key.

Next, let’s see how to handle the duplicated keys while producing the map using the Java Stream API.

For simplicity, we’ll use unit test assertions to verify whether each solution generates the expected results.

3. Generating a Map<Key, List<Value>> Using the groupingBy() Method

One idea to handle duplicated keys in a map is to make the key associate multiple values in a collection, such as Map<String, List<City>>. Some popular libraries have provided MultiMap types, such as Guava’s Multimap and Apache Commons MultiValuedMap, to handle multiple-value maps more easily.

In this tutorial, we’ll stick to the standard Java API. Therefore, we’ll use the groupingBy() collector to produce a Map<String, List<City>> result, as the groupingBy() method can group objects by some property as keys and store the objects in a Map instance:

Map<String, List<City>> resultMap = CITY_INPUT.stream()
  .collect(groupingBy(City::getName));

assertEquals(4, resultMap.size());
assertEquals(Arrays.asList(new City("Paris", "France"), new City("Paris", "Texas, USA")),
  resultMap.get("Paris"));

As we can see in the test above, the map result produced by the groupingBy() collector contains four entries. Also, the two “Paris” city instances are grouped under the key “Paris“.

Therefore, using the multi-value map approach can solve the key duplication problem. However, this approach returns Map<String, List<City>>. If we require Map<String, City> as the return type, we can no longer group the objects with the duplicated key together in a collection.

So next, let’s see how to deal with the duplicated keys in this situation.

4. Using the toMap() Method and Handling the Duplicated Keys

Stream API has provided the toMap() collector method to collect a stream into a Map.

Furthermore, the toMap() method allows us to specify a merge function that will be used to combine values associated with duplicate keys.

For example, we can use a simple lambda expression to ignore the latter City objects if their names have been collected already:

Map<String, City> resultMap1 = CITY_INPUT.stream()
  .collect(toMap(City::getName, Function.identity(), (first, second) -> first));

assertEquals(4, resultMap1.size());
assertEquals(new City("Paris", "France"), resultMap1.get("Paris"));

As the test above shows, as France’s Paris is before Paris in Texas, USA, in the input list, the resulting map only contains the city Paris in France.

Alternatively, if we want always to overwrite the existing entry in the map when a duplicated key occurs, we can adjust the lambda expression to return the second City object:

Map<String, City> resultMap2 = CITY_INPUT.stream()
  .collect(toMap(City::getName, Function.identity(), (first, second) -> second));

assertEquals(4, resultMap2.size());
assertEquals(new City("Paris", "Texas, USA"), resultMap2.get("Paris"));

If we run the test, it passes. So, this time, the key “Paris” associates Paris in Texas, USA.

Of course, in a real project, we may have a sophisticated requirement other than simply skipping or overwriting. We can always implement the required merge logic in the merge function.

Finally, let’s see another example of merging two “Paris” cities’ locatedIn properties as a new City instance and putting this newly merged Paris instance to the map result:

Map<String, City> resultMap3 = CITY_INPUT.stream()
  .collect(toMap(City::getName, Function.identity(), (first, second) -> {
      String locations = first.getLocatedIn() + " and " + second.getLocatedIn();
      return new City(first.getName(), locations);
  }));

assertEquals(4, resultMap2.size());
assertEquals(new City("Paris", "France and Texas, USA"), resultMap3.get("Paris"));

5. Conclusion

In this article, we’ve explored two approaches to handling duplicated keys when producing a Map result using Stream API:

• groupingBy() – Create a Map result in the type Map<Key, List<Value>>
• mapTo() – Allows us to implement the merge logic in the merge function