Collectors.toMap and working with maps

For this lesson, we'll focus on the stream side of map work: the toMap overloads, duplicate-key policies, null-value traps, ordered and sorted suppliers, toConcurrentMap, and transformations that start from map.entrySet().stream(). We will link to Everyday Map operations for loop-based Map methods, and to Collectors deep dive for the general Collector API.

01Picture it first: labels, collisions and the output box

Picture a belt of user records. The key mapper prints the label on the box, the value mapper decides what goes inside, and the merge function is the tie-breaker when two boxes get the same label. The map supplier chooses the shelf: unordered HashMap, insertion-ordered LinkedHashMap, sorted TreeMap, or a concurrent map.

Fig. 1

A stream flows through key and value mappers into a map; duplicate keys go through a merge function and the supplier chooses HashMap, LinkedHashMap or TreeMap

Notice the two decisions that candidates often blend together. Duplicate policy is not the same as map type. You can sum duplicate values into a HashMap, keep the last value in a LinkedHashMap, or reject duplicates in a TreeMap.

02toMap under the hood: the overloads you actually use

import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

record User(String id, String name) { }

public class ToMapDuplicateDemo {
    public static void main(String[] args) {
        List<User> users = List.of(
                new User("u1", "Mina"),
                new User("u2", "Ravi"),
                new User("u1", "Mira")
        );

        try {
            users.stream().collect(Collectors.toMap(User::id, User::name));
        } catch (IllegalStateException duplicate) {
            System.out.println(duplicate.getMessage());
            // Duplicate key u1 (attempted merging values Mina and Mira)
        }

        Map<String, User> firstUserById = users.stream().collect(
                Collectors.toMap(
                        User::id,
                        Function.identity(),
                        (first, second) -> first
                )
        );

        System.out.println(firstUserById.get("u1").name()); // Mina
    }
}