List to Map in Java Streams — Collectors.toMap, Duplicates, and Map Suppliers

Use `Collectors.toMap(keyMapper, valueMapper)` to convert a list to a map. There are four overloads, and you almost always need to know about all of them.

Four overloads

• toMap(k, v) — throws on duplicate keys
• toMap(k, v, mergeFunction) — collide-safe; pick first/last/combine
• toMap(k, v, merge, mapSupplier) — pick the Map impl: LinkedHashMap, TreeMap, EnumMap, pre-sized HashMap
• toUnmodifiableMap(k, v) — Java 10+ for immutable result (no merge/supplier overloads)

The duplicate-key gotcha — the most common mistake

• Two-arg toMap is strict: throws IllegalStateException on duplicate keys
• Historical: design committee chose fail-loud over silent data loss
• Without merge, the collector can't know whether to keep first, last, or combine

Three merge strategies

• (existing, dup) -> existing — keep first
• (existing, dup) -> dup — keep last
• Integer::sum, String::concat, custom op — combine

The null-value NPE quirk

• toMap throws NPE if the value mapper returns null
• Even though HashMap.put(key, null) works fine
• Internal implementation uses Map.merge which forbids null values
• Workarounds:

  • Filter null values before collecting
  • Replace null with a sentinel
  • Use Optional.ofNullable(...) as the value
  • Build map manually with a for-loop

Picking the Map impl — four-arg overload

• LinkedHashMap::new — insertion order (encounter order in stream)
• TreeMap::new — sorted by key
• EnumMap::new — most efficient for enum keys
• () -> new HashMap<>(initialCap) — pre-sized to avoid resize
• For parallel — use toConcurrentMap which gives ConcurrentHashMap

`toUnmodifiableMap` (Java 10+)

• Immutable result; throws on mutation
• Throws NPE on null keys or values
• No merge or supplier overload
• For merge + immutable, wrap with Collections.unmodifiableMap after toMap
• Or use collectingAndThen(toMap(...), Collections::unmodifiableMap)

`toMap` vs `groupingBy` — the decision

Use toMap when

• Key is unique
• You want flat Map (one value per key)
• Lookup tables, indexing by ID

Use groupingBy when

• Key is not unique — multiple values per key
• You want Map> or aggregated values
• Histograms, partitioning, aggregations

Easy mistake — using toMap for a not-actually-unique key, hitting IllegalStateException in production

• If you're at all unsure: add a merge function defensively OR switch to groupingBy

Counting pattern — use groupingBy

• groupingBy(Function.identity(), counting()) — idiomatic
• Don't fight it with toMap(id, w -> 1L, Long::sum) — less readable

Boolean partitioning — use partitioningBy

• partitioningBy(predicate) — returns Map> with both keys present
• Don't use toMap for this

`Function.identity()`

• The canonical 'use the element as-is' mapper
• toMap(User::getId, Function.identity()) — map of users by ID

Performance

• toMap slightly faster than groupingBy for unique keys (no list allocation)
• For typical N (< 10k), negligible
• Pre-size HashMaps for very large input to avoid resize
• For very-parallel: toConcurrentMap writes directly to ConcurrentHashMap

No Stream.toMap()

• Java 16+ added Stream.toList() for lists
• No equivalent for maps — always go through Collectors.toMap

Recommendation: Use `Collectors.toMap(keyMapper, valueMapper)` as your default for converting a list to a map of unique keys; always provide a merge function when there's any chance of duplicate keys to avoid IllegalStateException in production. Pick `(existing, dup) -> existing` for keep-first, `(existing, dup) -> dup` for keep-last, or a combine like Integer::sum for aggregations. Use the four-arg overload with LinkedHashMap::new for insertion order, TreeMap::new for sorted output, or EnumMap::new for enum keys. For immutable results, use `toUnmodifiableMap` (Java 10+); for immutable + merge, wrap with collectingAndThen(toMap(...), Collections::unmodifiableMap). Watch the null-value NPE quirk — filter or replace nulls before collecting. For one-to-many (multiple values per key), don't fight toMap: switch to `groupingBy` which is the right tool. For counting, prefer `groupingBy(k, counting())` over toMap with merge — it's idiomatic. For boolean splitting, use `partitioningBy`. The mental shortcut: toMap = unique keys, flat values; groupingBy = many-to-one, aggregate values; partitioningBy = boolean two-bucket. Pick the right tool, always handle duplicates and nulls explicitly.