Java Academy · Lesson

Building a Custom Collector

Implement the Collector interface to create a reusable aggregation for a domain-specific use case.

Lesson 4 of 413 steps

Building a Custom Collector is a free Java Academy lesson on CoddyKit. This is lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Java Academy learning path, and your progress syncs across the web and the CoddyKit app. The Java Academy course includes 4 lessons in total.

Why Build a Custom Collector?

When built-in collectors don't fit your domain, implement the Collector<T, A, R> interface to create reusable, composable aggregation logic. T=input, A=mutable accumulator, R=result.

The Collector Interface

A Collector has four components:

supplier() — creates the initial accumulator
accumulator() — folds one element into the accumulator
combiner() — merges two accumulators (for parallel streams)
finisher() — transforms the accumulator into the final result
characteristics() — optimization hints

Collector.of() Factory

The easiest way to create a custom collector is Collector.of() without implementing the interface directly:

import java.util.stream.*;

// Collector that builds a comma-separated String
Collector<String, StringBuilder, String> csvCollector = Collector.of(
    StringBuilder::new,                     // supplier
    (sb, s) -> {
        if (sb.length() > 0) sb.append(',');
        sb.append(s);
    },                                       // accumulator
    (a, b) -> {
        if (a.length() > 0 && b.length() > 0) a.append(',');
        a.append(b); return a;
    },                                       // combiner
    StringBuilder::toString                  // finisher
);

String csv = Stream.of("Alice","Bob","Carol").collect(csvCollector);
System.out.println(csv); // Alice,Bob,Carol

Custom Collector: TopN

Build a collector that keeps only the top N elements by a comparator:

import java.util.*;
import java.util.stream.*;

static <T> Collector<T, ?, List<T>> topN(int n, Comparator<T> comp) {
    return Collector.of(
        () -> new ArrayList<T>(),
        (list, e) -> {
            list.add(e);
            list.sort(comp.reversed());
            if (list.size() > n) list.remove(list.size() - 1);
        },
        (a, b) -> {
            a.addAll(b);
            a.sort(comp.reversed());
            while (a.size() > n) a.remove(a.size() - 1);
            return a;
        },
        Collector.Characteristics.UNORDERED
    );
}

Using TopN Collector

Apply the custom TopN collector on a stream:

List<Integer> top3 = Stream.of(5,2,9,1,7,3,8)
    .collect(topN(3, Comparator.naturalOrder()));
System.out.println(top3); // [9, 8, 7]

Characteristics Flags

Three optional characteristics tune stream optimization:

IDENTITY_FINISH — finisher is identity; skip it
UNORDERED — result order doesn't matter
CONCURRENT — accumulator can be called concurrently

Setting the wrong flag (e.g., CONCURRENT without thread-safety) causes bugs.

Custom Collector: Running Average

Maintain a running average without a second pass:

record RunningAvg(long count, double sum) {
    RunningAvg add(double v) { return new RunningAvg(count+1, sum+v); }
    RunningAvg merge(RunningAvg o) { return new RunningAvg(count+o.count, sum+o.sum); }
    double avg() { return count == 0 ? 0 : sum / count; }
}

Collector<Double, RunningAvg[], Double> avgCollector = Collector.of(
    () -> new RunningAvg[]{new RunningAvg(0, 0)},
    (a, v) -> a[0] = a[0].add(v),
    (a, b) -> { a[0] = a[0].merge(b[0]); return a; },
    a -> a[0].avg()
);

double avg = Stream.of(10.0, 20.0, 30.0).collect(avgCollector);
System.out.println(avg); // 20.0

Implementing the Collector Interface Directly

For more control, implement Collector<T,A,R> as a class:

import java.util.function.*;
import java.util.stream.*;

class StringJoiningCollector implements Collector<String, List<String>, String> {
    private final String delimiter;
    StringJoiningCollector(String delimiter) { this.delimiter = delimiter; }
    public Supplier<List<String>> supplier() { return ArrayList::new; }
    public BiConsumer<List<String>, String> accumulator() { return List::add; }
    public BinaryOperator<List<String>> combiner() {
        return (a,b) -> { a.addAll(b); return a; };
    }
    public Function<List<String>, String> finisher() {
        return list -> String.join(delimiter, list);
    }
    public Set<Characteristics> characteristics() { return Set.of(); }
}

Comparing Custom vs Built-in

Before writing a custom collector, check if composing built-in collectors achieves the same result — they're already tested and optimized:

// Instead of custom, compose:
Map<String, IntSummaryStatistics> stats = orders.stream().collect(
    Collectors.groupingBy(Order::status,
        Collectors.summarizingInt(Order::amount))
);
// This replaces many custom collector implementations

Thread Safety in Custom Collectors

If CONCURRENT characteristic is set, the accumulator is called from multiple threads simultaneously. The accumulator must then be thread-safe (e.g., use ConcurrentHashMap or AtomicLong). Without CONCURRENT, the combiner handles parallelism safely.

Real Use Case: Histogram Collector

Bucket numeric values into a histogram map:

Collector<Integer, Map<Integer, Long>, Map<Integer, Long>> histogram =
    Collector.of(
        LinkedHashMap::new,
        (map, val) -> map.merge(val / 10 * 10, 1L, Long::sum),
        (a, b) -> { b.forEach((k,v) -> a.merge(k,v,Long::sum)); return a; },
        Collector.Characteristics.IDENTITY_FINISH
    );

Map<Integer,Long> hist = Stream.of(5,15,25,12,8,22,18,3)
    .collect(histogram);
hist.forEach((bucket, cnt) -> System.out.println(bucket+"-"+(bucket+9)+": "+cnt));

Quick Check

Which Collector.Characteristics flag indicates that the finisher function is the identity transformation and can be skipped?

Answer it in the interactive lesson

Recap: Custom Collectors

Key takeaways:

Collector<T,A,R>: T=input, A=accumulator, R=result
Use Collector.of() for quick implementation without a class
supplier/accumulator/combiner/finisher/characteristics are the 5 parts
IDENTITY_FINISH, UNORDERED, CONCURRENT are optimization flags
Prefer composing built-in collectors; go custom only when needed

Free to start

Learn Java with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 104
Lessons: 374

Start learning free View the full course

Frequently Asked Questions

Is the “Building a Custom Collector” lesson free?

Yes — the full text of “Building a Custom Collector” is free to read here on the web. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Java Academy course, upgrade to CoddyKit PRO. The Java Academy course includes 4 lessons in total.

What will I learn in “Building a Custom Collector”?

Implement the Collector interface to create a reusable aggregation for a domain-specific use case. You practise Java Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Java Academy?

No prior experience is required. Java Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

How long does the “Building a Custom Collector” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Java Academy lesson?

Yes. Every Java Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Java Academy