Writing a custom collector

For this lesson, we'll focus on writing collectors, not memorizing every built-in one. We'll cover Collector.of, implementing Collector as a class, a bounded top-N collector, an immutable sorted set collector, a batching collector, combiner correctness, characteristics, and Java 22+ Gatherers as the future for some stateful stream work. The general collector model is covered in Collectors deep dive.

01Picture it first: many bowls, one plated result

Picture two cooks preparing the same recipe from two halves of a conveyor belt. Each cook gets a bowl from the supplier, adds ingredients with the accumulator, and then the combiner pours one bowl into the other. The finisher plates the final bowl.

Fig. 1

A custom collector creates mutable containers with a supplier, accumulates stream elements, combines partial containers in parallel, and finishes as the final result

The mental model is mutable inside, stable outside. Most collectors mutate a private work container because that is efficient. The result can still be immutable if the finisher copies or wraps it.

02Collector.of under the hood

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.stream.Collector;

public class CollectorOfDemo {
    static <T> Collector<T, List<T>, List<T>> toUnmodifiableListLike() {
        return Collector.of(
                ArrayList::new,
                List::add,
                (left, right) -> {
                    left.addAll(right);
                    return left;
                },
                Collections::unmodifiableList
        );
    }

    public static void main(String[] args) {
        List<String> ids = List.of("u1", "u2", "u3").stream()
                .collect(toUnmodifiableListLike());

        System.out.println(ids); // [u1, u2, u3]
    }
}