How do you implement a custom Collector, and what are the roles of supplier, accumulator, combiner, finisher, and characteristics?

## Why custom collectors Most aggregations are covered by built-in `Collectors`, but occasionally you need behavior none of them provide (a bespoke container, a special merge, an unusual finishing transform). The `Collector` interface lets you define exactly how a stream is folded. ## The type parameters: Collector<T, A, R> - **T** — the input element type (what the stream contains). - **A** — the *mutable accumulation* type, the intermediate container used while collecting (often hidden/internal). - **R** — the final result type returned to the caller. ## The four functions 1. **supplier — `Supplier<A>`**: produces a **new, empty mutable container** each time collecting starts (and once per thread in parallel). E.g. `ArrayList::new`, `() -> new int[1]`, `StringBuilder::new`. 2. **accumulator — `BiConsumer<A, T>`**: folds **one element** into the container by mutating it. E.g. `List::add`, `(sb, s) -> sb.append(s)`. It mutates in place and returns nothing. 3. **combiner — `BinaryOperator<A>`**: takes **two partial containers and merges them into one**, returning the merged container. It is invoked **only for parallel streams**, where the data is split, each chunk accumulated into its own container, and the partials combined. E.g. `(a, b) -> { a.addAll(b); return a; }`. 4. **finisher — `Function<A, R>`**: performs the **final transform** from the accumulation container to the result. If `A` and `R` are identical, the finisher is `Function.identity()` (or `i -> i`). ## characteristics — `Set<Collector.Characteristics>` Flags that let the runtime optimize: - **`IDENTITY_FINISH`**: the finisher is the identity function, so the runtime may **skip calling it** and just cast `A` to `R`. Only set this if `A` really equals `R`. - **`UNORDERED`**: the result does **not** depend on encounter order (e.g. a `Set`, a sum). Lets the runtime relax ordering for speed. - **`CONCURRENT`**: a **single accumulation container may be shared across threads**, so the accumulator must be thread-safe and the combiner is effectively unused. Concurrent collecting is only used when the stream is also `UNORDERED` (or the source is unordered) — otherwise the runtime falls back to per-thread containers + combiner. ## Building one Use the factory `Collector.of(supplier, accumulator, combiner)` (identity finisher, no special characteristics) or `Collector.of(supplier, accumulator, combiner, finisher, characteristics...)`. Implementing the interface directly is rarely necessary. ## How the pieces interact (sequential) ``` A container = supplier.get(); for (T e : elements) accumulator.accept(container, e); R result = finisher.apply(container); ``` ## How they interact (parallel, non-concurrent) The stream is split; each chunk runs the sequential loop into its **own** container; the partials are merged pairwise with the **combiner**; the merged container is finished. This is why the combiner must be **associative** and consistent with the accumulator: combining must yield the same result as accumulating all elements into one container. ## Correctness rules (interview gold) - The container **must be mutable** (you accumulate by mutation). - accumulator and combiner must be **consistent**: combine(acc(empty,a), acc(empty,b)) must equal acc(acc(empty,a), b) up to result equality. - The combiner must be **associative**. - Set `IDENTITY_FINISH` **only** when `A == R`. - Set `CONCURRENT` only with a **thread-safe** container and accept the unordered constraint. ## Worked example: a collector to an immutable comma list See the code example — supplier `StringJoiner::new` (with delimiter), accumulator appends, combiner merges two joiners, finisher `toString`. (Of course `joining` already does this; it's illustrative.) ## Term glossary - **Supplier<A>**: zero-arg factory returning a new `A`. - **BiConsumer<A,T>**: takes an `A` and a `T`, returns nothing, used for side-effecting accumulation. - **BinaryOperator<A>**: takes two `A`s, returns an `A`. - **Associative**: `(x∘y)∘z == x∘(y∘z)`; required so parallel merge order doesn't matter.