What guarantees does groupingBy make about result mutability, ordering, null handling, and parallel execution, and when would you reach for groupingByConcurrent?

## What is and is not guaranteed The `Collectors.groupingBy` contract promises only: the result is a `Map<K, D>` mapping each distinct classifier key to the downstream result for that group. Everything else is an *implementation detail* unless you make it explicit. ### Map and list type / mutability - One-arg `groupingBy` currently returns a `HashMap` with `ArrayList` values, both mutable — but the spec does not pin this. **Do not depend on it.** If you need a guarantee, pass a `mapFactory` (3-arg form) and/or wrap with `collectingAndThen(..., Collections::unmodifiableMap)`. ### Ordering - A `HashMap` has **no ordering**. For sorted keys use `TreeMap::new`; for insertion (encounter) order use `LinkedHashMap::new`. Within each group, list values follow encounter order on a sequential stream. ### Null handling - A `null` *key* from the classifier throws `NullPointerException` in the standard collector (it delegates to `Map.merge`/`computeIfAbsent`, which reject null keys). Guard by filtering nulls or mapping them to a sentinel key. Null *elements* may be fine depending on the downstream (`toList` accepts nulls; `toSet`/`counting` generally do too), but treat null-heavy data carefully. ## Sequential vs parallel A `Collector` defines five things: a **supplier** (new empty container), an **accumulator** (fold one element in), a **combiner** (merge two partial containers), a **finisher**, and **characteristics**. On a **parallel** stream the framework splits the data, each thread builds a partial result with the supplier+accumulator, and the **combiner** merges them. For plain `groupingBy`, the combiner merges two `HashMap`s key-by-key (and merges the per-group downstream results). This works correctly but the merge can dominate cost when keys are many or groups large. ## groupingByConcurrent `Collectors.groupingByConcurrent(classifier[, mapFactory], downstream)` returns a **`ConcurrentHashMap`** and is a **CONCURRENT + UNORDERED** collector. Instead of each thread building its own map and merging, all threads accumulate **into one shared concurrent map**. This avoids the merge step. It pays off only when **all** of these hold: 1. The stream is **parallel** (`.parallelStream()` / `.parallel()`). 2. You can tolerate losing **encounter order** (it is UNORDERED — make the stream unordered too, e.g. `.unordered()`, to let the framework skip order bookkeeping). 3. The dataset is large enough that contention on the concurrent map is outweighed by skipping merges. 4. The downstream collector itself behaves well under concurrent accumulation. If the stream is sequential, `groupingByConcurrent` gives no benefit (and a `ConcurrentHashMap` is slightly heavier than a `HashMap`). ## Making results immutable Wrap the whole thing or each group: ```java Map<String, List<Person>> immutable = people.stream().collect( Collectors.collectingAndThen( Collectors.groupingBy(Person::city), Collections::unmodifiableMap)); ``` or seal each list with an inner `collectingAndThen(toList(), List::copyOf)`. ## Decision guidance - Default to plain `groupingBy` on a sequential stream — simplest and usually fast enough. - Reach for parallel + `groupingByConcurrent` only after measuring, with large data, order-insensitive logic, and associative downstreams (`counting`, `summingInt`, `toSet`). - Always specify the map factory when order or type matters; never silently rely on `HashMap`/`ArrayList` identity. ## Common traps - Assuming the result map is sorted or insertion-ordered. - Assuming the result is immutable (it is not by default) or, conversely, that it is safe to mutate concurrently (a plain `groupingBy` result is a plain `HashMap`). - Using `groupingByConcurrent` on a sequential stream expecting a speedup. - Letting a `null` classifier key slip through and throwing at runtime.