1. Introduction

In this quick tutorial, we'll demonstrate how to merge two maps using the Java 8 capabilities.

To be more specific, we'll examine different merging scenarios including maps having duplicate entries.

2. Initialization

As a start, let's define two Map instances:

private static Map<String, Employee> map1 = new HashMap<>();
private static Map<String, Employee> map2 = new HashMap<>();

The Employee class looks like this:

public class Employee {
    private Long id;
    private String name;
    // constructor, getters, setters

Then, we can push some data into the Map instances:

Employee employee1 = new Employee(1L, "Henry");
map1.put(employee1.getName(), employee1);
Employee employee2 = new Employee(22L, "Annie");
map1.put(employee2.getName(), employee2);
Employee employee3 = new Employee(8L, "John");
map1.put(employee3.getName(), employee3);

Employee employee4 = new Employee(2L, "George");
map2.put(employee4.getName(), employee4);
Employee employee5 = new Employee(3L, "Henry");
map2.put(employee5.getName(), employee5);

Note, that we have identical keys for employee1 and employee5 entries in our maps which we'll use later.

3. Map.merge()

Java 8 adds a new merge() function into the java.util.Map interface.

Here is how the merge() function works: If the specified key is not already associated with a value or the value is null, it associates the key with the given value.

Otherwise, it replaces the value with the results of the given remapping function. If the result of the remapping function is null, it removes the result.

First, let's construct a new HashMap by copying all the entries from the map1:

Map<String, Employee> map3 = new HashMap<>(map1);

Next, let's introduce the merge() function along with merging rule:

map3.merge(key, value, (v1, v2) -> new Employee(v1.getId(),v2.getName())

Finally, we'll iterate over the map2 and merge the entries into map3:

  (key, value) -> map3.merge(key, value, (v1, v2) -> new Employee(v1.getId(),v2.getName())));

Let's run the program and print the content of map3:

John=Employee{id=8, name='John'}
Annie=Employee{id=22, name='Annie'}
George=Employee{id=2, name='George'}
Henry=Employee{id=1, name='Henry'}

As a result, our combined Map has all the elements of the previous HashMap entries. Entries with duplicate keys have been merged into one entry.

Also, we notice that the Employee object of the last entry has the id from the map1, and value is picked from map2.

This is because of the rule we defined in our merger function:

(v1, v2) -> new Employee(v1.getId(), v2.getName())

4. Stream.concat()

The Stream API in Java 8 can also provide an easy solution to our problem. First, we need to combine our Map instances into one Stream. That's exactly what Stream.concat() operation does:

Stream combined = Stream.concat(map1.entrySet().stream(), map2.entrySet().stream());

Here we pass the map entry sets as parameters. Next, we need to collect our result into a new Map. For that we can use Collectors.toMap():

Map<String, Employee> result = combined.collect(
  Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));

As a result, the collector will use the existing keys and values of our maps. But this solution is far from being perfect. As soon as our collector meets entries with duplicate keys, it'll throw an IllegalStateException.

To handle this issue, we simply add a third “merger” lambda parameter into our collector:

(value1, value2) -> new Employee(value2.getId(), value1.getName())

It will use the lambda expression every time a duplicate key is detected.

Finally, putting all together:

Map<String, Employee> result = Stream.concat(map1.entrySet().stream(), map2.entrySet().stream())
    (value1, value2) -> new Employee(value2.getId(), value1.getName())));

Finally, let's run the code and see the results:

George=Employee{id=2, name='George'}
John=Employee{id=8, name='John'}
Annie=Employee{id=22, name='Annie'}
Henry=Employee{id=3, name='Henry'}

As we see, the duplicate entries with the key “Henry” were merged into a new key-value pair where the id of the new Employee was picked from the map2 and the value from map1.

5. Stream.of()

To continue to use the Stream API, we can turn our Map instances into a unified stream with the help of Stream.of().

Here we don't have to create an additional collection to work with the streams:

Map<String, Employee> map3 = Stream.of(map1, map2)
  .flatMap(map -> map.entrySet().stream())
    (v1, v2) -> new Employee(v1.getId(), v2.getName())));

First, we transform map1 and map2 into a single stream. Next, we convert the stream into the map. As we can see, the last argument of toMap() is a merging function. It solves the duplicate keys problem by picking the id field from v1 entry, and the name from v2.

The printed map3 instance after running the program:

George=Employee{id=2, name='George'}
John=Employee{id=8, name='John'}
Annie=Employee{id=22, name='Annie'}
Henry=Employee{id=1, name='Henry'}

6. Simple Streaming

Additionally, we can use a stream() pipeline to assemble our map entries. The code snippet below demonstrates how to add the entries from map2 and map1 by ignoring the duplicate entries:

Map<String, Employee> map3 = map2.entrySet()
    (v1, v2) -> new Employee(v1.getId(), v2.getName()),
  () -> new HashMap<>(map1)));

As we expect, the results after the merge are:

{John=Employee{id=8, name='John'}, 
Annie=Employee{id=22, name='Annie'}, 
George=Employee{id=2, name='George'}, 
Henry=Employee{id=1, name='Henry'}}

7. StreamEx

In addition to solutions that are provided by the JDK, we can also use the popular StreamEx library.

Simply put, StreamEx is an enhancement for the Stream API and provides many additional useful methods. We'll use an EntryStream instance to operate on key-value pairs:

Map<String, Employee> map3 = EntryStream.of(map1)
  .toMap((e1, e2) -> e1);

The idea is to merge the streams of our maps into one. Then we collect the entries into the new map3 instance. Important to mention, the (e1, e2) -> e1 expression as it helps to define the rule for dealing with the duplicate keys. Without it, our code will throw an IllegalStateException.

And now, the results:

{George=Employee{id=2, name='George'}, 
John=Employee{id=8, name='John'}, 
Annie=Employee{id=22, name='Annie'}, 
Henry=Employee{id=1, name='Henry'}}

8. Summary

In this short article, we learned different ways of merging maps in Java 8. More specifically, we used Map.merge(), Stream API, StreamEx library.

As always, the code used during the discussion can be found over on GitHub.