Collectors are the strategies that tell a Stream how to turn a flow of elements into a concrete result such as a List, Map, number, or custom DTO. Conceptually, a collector answers the question: “Given a stream of T, how do I build a result R in a single reduction step?”
1. What is a Collector?
A Collector is a mutable reduction that accumulates stream elements into a container and optionally transforms that container into a final result. This is the formal definition of the Collector interface:
public interface Collector<T, A, R> {
Supplier<A> supplier();
BiConsumer<A, T> accumulator();
BinaryOperator<A> combiner();
Function<A, R> finisher();
Set<Characteristics> characteristics();
}
Where:
T – input element type coming from the stream. A – mutable accumulator type used during collection (e.g. ArrayList<T>, Map<K,V>, statistics object). R – final result type (may be the same as A).
The functions have clear responsibilities:
supplier – creates a new accumulator instance A. accumulator – folds each element T into the accumulator A. combiner – merges two accumulators (essential for parallel streams). finisher – converts A to R (often identity, sometimes a transformation like making the result unmodifiable). characteristics – hints like CONCURRENT, UNORDERED, IDENTITY_FINISH that allow stream implementations to optimize.
The Collectors utility class provides dozens of ready‑made collectors so you rarely need to implement Collector yourself. You use them via the Stream.collect(...) terminal operation:
<R> R collect(Collector<? super T, ?, R> collector)
You can think of this as: collector = recipe, and collect(recipe) = “execute this aggregation recipe on the stream.”
2. Collectors vs Collector
Two related but distinct concepts:
Collector (interface)
- Describes what a mutable reduction looks like in terms of
supplier, accumulator, combiner, finisher, characteristics.
Collectors (utility class)
- Provides static factory methods that create
Collector instances: toList(), toMap(...), groupingBy(...), mapping(...), teeing(...), etc.
As an engineer, you almost always use the factory methods on Collectors, and only occasionally need to implement a custom Collector directly.
3. Collectors.toMap – building maps with unique keys
Collectors.toMap builds a Map by turning each stream element into exactly one key–value pair. It is appropriate when you conceptually want one aggregate value per key.
3.1 Overloads and semantics
Key overloads:
toMap(keyMapper, valueMapper)
- Requires keys to be unique; on duplicates, throws
IllegalStateException.
toMap(keyMapper, valueMapper, mergeFunction)
- Uses
mergeFunction to decide what to do with duplicate keys (e.g. pick first, pick max, sum).
toMap(keyMapper, valueMapper, mergeFunction, mapSupplier)
- Also allows specifying the
Map implementation (e.g. LinkedHashMap, TreeMap).
The explicit mergeFunction parameter is a deliberate design: the JDK authors wanted to prevent silent data loss, forcing you to define your collision semantics.
3.2 Example
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public record City(String name, String country, int population) {}
void main() {
List<City> cities = List.of(
new City("Paris", "France", 2_140_000),
new City("Nice", "France", 340_000),
new City("Berlin", "Germany", 3_600_000),
new City("Hamburg", "Germany", 1_800_000)
);
// Country -> largest city by population, preserve insertion order
Map<String, City> largestCityByCountry = cities.stream()
.collect(Collectors.toMap(
City::country,
city -> city,
(c1, c2) -> c1.population() >= c2.population() ? c1 : c2,
LinkedHashMap::new
));
System.out.println(largestCityByCountry);
}
Rationale:
- We express domain logic (“keep the most populous city per country”) with a merge function instead of an extra grouping pass.
LinkedHashMap documents that iteration order matters (e.g. for responses or serialization) and keeps output deterministic.
4. Collectors.groupingBy – grouping and aggregating
Collectors.groupingBy is the collector analogue of SQL GROUP BY: it classifies elements into buckets and aggregates each bucket with a downstream collector. You use it when keys are not unique and you want collections or metrics per key.
4.1 Overloads and default shapes
Representative overloads:
groupingBy(classifier)
Map<K, List<T>>, using toList downstream.
groupingBy(classifier, downstream)
Map<K, D> where D is the downstream result (sum, count, set, custom type).
groupingBy(classifier, mapFactory, downstream)
- Adds control over the map implementation.
This design splits the problem into classification (classifier) and aggregation (downstream), which makes collectors highly composable.
4.2 Example
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public record Order(String city, String status, double amount) {}
void main() {
List<Order> orders = List.of(
new Order("Auckland", "NEW", 100),
new Order("Auckland", "NEW", 200),
new Order("Auckland", "SHIPPED", 150),
new Order("Wellington", "NEW", 300)
);
// City -> list of orders
Map<String, List<Order>> ordersByCity = orders.stream()
.collect(Collectors.groupingBy(Order::city));
// City -> total amount
Map<String, Double> totalByCity = orders.stream()
.collect(Collectors.groupingBy(
Order::city,
Collectors.summingDouble(Order::amount)
));
// Status -> number of orders
Map<String, Long> countByStatus = orders.stream()
.collect(Collectors.groupingBy(
Order::status,
Collectors.counting()
));
System.out.println("Orders by city: " + ordersByCity);
System.out.println("Total by city: " + totalByCity);
System.out.println("Count by status: " + countByStatus);
}
Rationale:
- We avoid explicit
Map mutation and nested conditionals; aggregation logic is declarative and parallel‑safe by construction.
- Downstream collectors like
summingDouble and counting can be reused for other groupings.
5. Composing collectors – mapping, filtering, flatMapping, collectingAndThen
Collectors are designed to be nested, especially as downstreams of groupingBy or partitioningBy. This composability is what turns them into a mini DSL for aggregation.
5.1 mapping – transform before collecting
mapping(mapper, downstream) applies a mapping to each element, then forwards the result to a downstream collector. Use it when you don’t want to store the full original element in the group.
Example: department → distinct employee names.
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;
public record Employee(String department, String name) {}
void main() {
List<Employee> employees = List.of(
new Employee("Engineering", "Alice"),
new Employee("Engineering", "Alice"),
new Employee("Engineering", "Bob"),
new Employee("Sales", "Carol")
);
Map<String, Set<String>> namesByDept = employees.stream()
.collect(Collectors.groupingBy(
Employee::department,
Collectors.mapping(Employee::name, Collectors.toSet())
));
System.out.println(namesByDept);
}
Rationale:
- We avoid storing full
Employee objects when we only need names, reducing memory and making the intent explicit.
5.2 filtering – per-group filtering
filtering(predicate, downstream) (Java 9+) filters elements at the collector level. Unlike stream.filter, it keeps the outer grouping key even if the filtered collection becomes empty.
Example: city → list of large orders (≥ 150), but preserve all cities as keys.
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public record Order(String city, double amount) {}
void main() {
List<Order> orders = List.of(
new Order("Auckland", 100),
new Order("Auckland", 200),
new Order("Wellington", 50),
new Order("Wellington", 300)
);
Map<String, List<Order>> largeOrdersByCity = orders.stream()
.collect(Collectors.groupingBy(
Order::city,
Collectors.filtering(
o -> o.amount() >= 150,
Collectors.toList()
)
));
System.out.println(largeOrdersByCity);
}
Rationale:
- This approach preserves the full key space (e.g. all cities), which can be important for UI or reporting, while still applying a per-group filter.
5.3 flatMapping – flatten nested collections
flatMapping(mapperToStream, downstream) (Java 9+) flattens nested collections or streams before collecting.
Example: department → set of all courses taught there.
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;
public record Staff(String department, List<String> courses) {}
void main() {
List<Staff> staff = List.of(
new Staff("CS", List.of("Algorithms", "DS")),
new Staff("CS", List.of("Computer Architecture")),
new Staff("Math", List.of("Discrete Maths", "Probability"))
);
Map<String, Set<String>> coursesByDept = staff.stream()
.collect(Collectors.groupingBy(
Staff::department,
Collectors.flatMapping(
s -> s.courses().stream(),
Collectors.toSet()
)
));
System.out.println(coursesByDept);
}
Rationale:
- Without
flatMapping, you’d get Set<Set<String>> or need an extra pass to flatten; this keeps it one-pass and semantically clear.
5.4 collectingAndThen – post-process a collected result
collectingAndThen(downstream, finisher) applies a finisher function to the result of the downstream collector.
Example: collect to an unmodifiable list.
import java.util.List;
import java.util.stream.Collectors;
void main() {
List<String> names = List.of("Alice", "Bob", "Carol");
List<String> unmodifiableNames = names.stream()
.collect(Collectors.collectingAndThen(
Collectors.toList(),
List::copyOf
));
System.out.println(unmodifiableNames);
}
Rationale:
- It encapsulates the “collect then wrap” pattern into a single collector, improving readability and signaling immutability explicitly.
5.5 Nested composition example
Now combine several of these ideas:
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;
public record Employee(String department, String city, String name, int age) {}
void main() {
List<Employee> employees = List.of(
new Employee("Engineering", "Auckland", "Alice", 30),
new Employee("Engineering", "Auckland", "Bob", 26),
new Employee("Engineering", "Wellington", "Carol", 35),
new Employee("Sales", "Auckland", "Dave", 40)
);
// Department -> City -> unmodifiable set of names for employees age >= 30
Map<String, Map<String, Set<String>>> result = employees.stream()
.collect(Collectors.groupingBy(
Employee::department,
Collectors.groupingBy(
Employee::city,
Collectors.collectingAndThen(
Collectors.filtering(
e -> e.age() >= 30,
Collectors.mapping(Employee::name, Collectors.toSet())
),
Set::copyOf
)
)
));
System.out.println(result);
}
Rationale:
- We express a fairly involved requirement in a single declarative pipeline and single pass, instead of multiple nested maps and loops.
- Each collector in the composition captures a small, local concern (grouping, filtering, mapping, immutability).
6. Collectors.teeing – two collectors, one pass
Collectors.teeing (Java 12+) runs two collectors over the same stream in one pass and merges their results with a BiFunction.
Signature:
public static <T, R1, R2, R> Collector<T, ?, R>
teeing(Collector<? super T, ?, R1> downstream1,
Collector<? super T, ?, R2> downstream2,
java.util.function.BiFunction<? super R1, ? super R2, R> merger)
Use teeing when you want multiple aggregates (min and max, count and average, etc.) from the same data in one traversal.
6.1 Example: Stats in one pass
import java.util.List;
import java.util.stream.Collectors;
public record Stats(long count, int min, int max, double average) {}
void main() {
List<Integer> numbers = List.of(5, 12, 19, 21);
Stats stats = numbers.stream()
.collect(Collectors.teeing(
Collectors.summarizingInt(Integer::intValue),
Collectors.teeing(
Collectors.minBy(Integer::compareTo),
Collectors.maxBy(Integer::compareTo),
(minOpt, maxOpt) -> new int[] {
minOpt.orElseThrow(),
maxOpt.orElseThrow()
}
),
(summary, minMax) -> new Stats(
summary.getCount(),
minMax[0],
minMax[1],
summary.getAverage()
)
));
System.out.println(stats);
}
Rationale:
- We avoid traversing
numbers multiple times or managing manual mutable state (counters, min/max variables).
- We can reuse existing collectors (
summarizingInt, minBy, maxBy) and compose them via teeing for a single-pass, parallelizable aggregation.
7. When to choose which collector
For design decisions, the following mental model works well:
| Scenario |
Collector pattern |
| One value per key, need explicit handling of collisions |
toMap (with merge & mapSupplier as needed) |
| Many values per key (lists, sets, or metrics) |
groupingBy + downstream (toList, counting, etc.) |
| Need per-group transformation/filtering/flattening |
groupingBy with mapping, filtering, flatMapping |
| Need post-processing of collected result |
collectingAndThen(...) |
| Two independent aggregates, one traversal |
teeing(collector1, collector2, merger) |
Viewed as a whole, collectors form a high-level, composable DSL for aggregation, while the Stream interface stays relatively small and general. Treating collectors as “aggregation policies” lets you reason about what result you want, while delegating how to accumulate, combine, and finish to the carefully designed mechanisms of the Collectors API.
Recent Comments