Collectors deep dive

For this lesson, we'll focus on the Collector API rather than every stream operation around it: supplier, accumulator, combiner, finisher, characteristics, the standard Collectors catalogue, downstream collectors, and the list-collecting methods that are easy to confuse. Interviewers ask this because it separates people who can call toList() from people who understand why groupingBy(..., counting()) works.

01Picture it first: a packing station with merge lanes

Picture a warehouse packing station. Each lane gets an empty carton from the supplier, workers drop items into that carton with the accumulator, and a merge worker combines cartons when the stream ran in parallel. At the end, the finisher may seal the carton and print a label, or it may hand the same carton straight to you.

That is the important mental model. A collector is allowed to build with one shape and publish another shape. joining() builds with a StringBuilder style accumulator but publishes a String; collectingAndThen(toList(), List::copyOf) builds a list and then freezes the boundary.

Fig. 1

A collector creates containers with a supplier, accumulates elements in parallel lanes, combines partial containers and runs a finisher to publish the result

Notice the parallel branch. If a collector has no valid combiner, it may pass every sequential demo and still be wrong for parallelStream(). The combiner is not optional decoration.

02Collector under the hood: the five functions

A collector is parameterized as Collector<T, A, R>. T is the stream element type, A is the mutable accumulation type, and R is the final result type. In Collectors.toList(), T is your element, A is a mutable list, and R is also a list.

import java.util.List;
import java.util.StringJoiner;
import java.util.stream.Collector;

record Order(String id, int cents) { }

public class CollectorPiecesDemo {
    public static void main(String[] args) {
        Collector<Order, StringJoiner, String> orderIds = Collector.of(
                () -> new StringJoiner(", "),
                (joiner, order) -> joiner.add(order.id()),
                StringJoiner::merge,
                StringJoiner::toString
        );

        String ids = List.of(
                        new Order("o-101", 1200),
                        new Order("o-102", 800),
                        new Order("o-103", 450))
                .stream()
                .collect(orderIds);

        System.out.println(ids); // o-101, o-102, o-103
    }
}

Notice four things:

• The supplier must create a fresh container. Reusing one static container is a data race waiting to happen.
• The accumulator mutates that container and usually returns nothing because the container itself is changing.
• The combiner must merge the right container into the left container and return the merged container.
• The finisher publishes the result. Here it converts StringJoiner to String, so this collector is not IDENTITY_FINISH.

The three most common characteristics are worth saying carefully. IDENTITY_FINISH means the accumulation object can be returned as the final result with no finisher conversion. UNORDERED means the collector does not care about encounter order. CONCURRENT means multiple threads may call the accumulator on the same result container, but it only helps when the stream and collector rules allow concurrent accumulation.