In this section, we will learn what the Map merge() method is and how to use it in Java.

What is Java Map merge() Method?

The Java Map merge() method is used to add a new entry to map object or replace the value of a currently existed key in that map object.

Basically, this method accepts a key and a value, as well as a reference to a method.

If the key was not in the target Map object, or it was but its value was set to null, then the key and the value we’ve set as the arguments of the method will be added to the map object.

But if the key is already in the map object and has a value (a non-null value) associated with it, then the reference method will be executed instead.

Java merge() Method Syntax:

default V merge(K key,

V value,

BiFunction<? super V,? super V,? extends V> remappingFunction)

merge() Method Parameters:

The merge method has three parameters:

• The first parameter is the key we want to look for in the target map object.
• The second parameter is the value we want to be set for the key if this key is not in the target map object or it is but its value is null.
• The third parameter is of type BiFunction which is a functional interface. This means the third argument is basically a reference to a method.

Here’s the signature of the reference method:

• It takes two arguments:
• The first argument is the old value associated with the specified key.
• The second argument is the new value that we’ve passed as the second argument to the merge() method.

Also, the return value of this method is a new value that will be set for the specified key in the target map object.

Note: the data type of both arguments and the return value of this reference method should be the same as the data type for the values in the target map object.

merge() Method Return Value:

The return value of this method is of the same data type as the values in the target map object and will be a new value that we want to set for the specified key (the first argument).

Note: the value null might also return if we didn’t set a value for the specified key (The second argument was set to null or the reference method returned a null value).

merge() Method Exceptions:

UnsupportedOperationException: We get this exception if this method is not supported in the target Map object.

ClassCastException: We get this exception if the data type of either specified key or value (the arguments) is incompatible compared to the data type on the target map object.

NullPointerException: We get this exception if either key or value (the arguments of the method) is null and the target map object does not permit a null value. Or even if the third argument of the method (the reference method) is set to null.

Example: using Map merge() method

import java.util.Map; 
import java.util.HashMap;
class Main{
    public static void main(String[] args) {
        Map<String,String> map = new HashMap<>();
        map.put("Omid","Dehghan");
        map.put("Jack","Bauer");
        map.put("Barack","Obama");
        map.put("Elon","Musk");
        map.put("Lex","Fridman");

        map.merge("Omid","Doe",(oldValue,newValue)->{
            return oldValue + " "+newValue;
        });
        System.out.println(map.get("Omid"));
    }
}

Output:

Dehghan Doe

As you can see, here the key “Omid” is already on the map. So here, the merge method won’t use the second argument (the value) to put it directly as the new value for the specified key, but it will run the reference method and pass the old and new values to this reference method instead. That’s how we ended up with the value you see in the output.