JAVA-230 · Lesson 4 of 12 · 21 min
Collectors and grouping
▶ Video coming soon A video version of this lesson is on the way.
Hamza's question from last week, how to count repairs of each kind in one pass, was the first thing on the whiteboard on Wednesday, October 6. Ingrid wrote Odile's monthly table across the top: kind of repair, how many, total minutes. "That table is a map," she said, "from kind to a number. Streams build maps with collectors." A collector is the recipe that the terminal operation collect follows to turn a stream's elements into a result: a list, a set, a map, a string, a count or a summary. The class Collectors, in java.util.stream, provides ready-made collectors, and the most useful of them, groupingBy, does in one line what used to take a loop, a map and a cluster of if statements.
Collecting into lists, sets and strings
The simplest collectors gather the elements into a container. Collectors.toList() gives a modifiable list (the stream method toList() from lesson 3 gives an unmodifiable one and is usually what you want). Collectors.toSet() drops duplicates, and Collectors.toCollection(TreeSet::new) lets you choose the collection, here a sorted set. Collectors.joining(", ") concatenates strings with a separator, and an overload adds a prefix and suffix. Collectors.counting(), summingInt, averagingInt and summarizingInt produce numbers, and are mostly used inside groupingBy, as the next sections show.
import java.util.*;
import java.util.stream.*;
public class Main {
record Sale(String code, int quantity, long priceCents) { }
public static void main(String[] args) {
List<Sale> sales = List.of(
new Sale("TUBE-700x25", 2, 899), new Sale("BELL", 1, 650),
new Sale("TUBE-700x25", 1, 899), new Sale("PAD-ROAD", 2, 1299),
new Sale("CHAIN-11", 1, 2499));
TreeSet<String> codes = sales.stream().map(Sale::code).collect(Collectors.toCollection(TreeSet::new));
String receipt = sales.stream()
.map(s -> s.quantity() + " x " + s.code())
.collect(Collectors.joining("; ", "[", "]"));
long units = sales.stream().collect(Collectors.summingInt(Sale::quantity));
IntSummaryStatistics stats = sales.stream().collect(Collectors.summarizingInt(Sale::quantity));
System.out.println("Codes sold: " + codes);
System.out.println("Receipt lines: " + receipt);
System.out.println("Units: " + units);
System.out.println("Lines: " + stats.getCount() + ", most on one line: " + stats.getMax()
+ ", average per line: " + stats.getAverage());
}
}Codes sold: [BELL, CHAIN-11, PAD-ROAD, TUBE-700x25] Receipt lines: [2 x TUBE-700x25; 1 x BELL; 1 x TUBE-700x25; 2 x PAD-ROAD; 1 x CHAIN-11] Units: 7 Lines: 5, most on one line: 2, average per line: 1.4
What this code does
toCollection(TreeSet::new) collects the four distinct codes in sorted order, which a plain toSet would not promise. joining builds one string with a separator, prefix and suffix. summarizingInt returns count, sum, minimum, maximum and average together, which is handy when a report needs several of them.
groupingBy: the one-pass report
Collectors.groupingBy(classifier) puts each element into a bucket chosen by the classifier function and returns a Map from bucket key to a list of elements. Its real power is the second argument, a downstream collector, which says what to do with each bucket instead of keeping a list: count it, sum a field, average a field, or even group it again. The third, optional argument chooses the kind of map. This matters for reports: groupingBy with no map argument returns a HashMap, whose order is not defined and can change between runs or Java versions. For a printed report, ask for a TreeMap (sorted by key) or, with an enum key, an EnumMap (in the order the constants are declared).
import java.util.*;
import java.util.stream.*;
public class Main {
enum Kind { FLAT, BRAKES, GEARS, WHEEL_TRUE, TUNE_UP }
record Repair(int ticket, Kind kind, int minutes) { }
public static void main(String[] args) {
List<Repair> september = List.of(
new Repair(502, Kind.FLAT, 20), new Repair(503, Kind.BRAKES, 45),
new Repair(504, Kind.FLAT, 15), new Repair(505, Kind.GEARS, 60),
new Repair(506, Kind.WHEEL_TRUE, 40), new Repair(509, Kind.FLAT, 25),
new Repair(510, Kind.BRAKES, 35), new Repair(511, Kind.TUNE_UP, 80));
Map<Kind, List<Repair>> byKind = september.stream()
.collect(Collectors.groupingBy(Repair::kind));
System.out.println("FLAT tickets: " + byKind.get(Kind.FLAT).stream().map(Repair::ticket).toList());
Map<Kind, Long> counts = september.stream()
.collect(Collectors.groupingBy(Repair::kind, () -> new EnumMap<>(Kind.class), Collectors.counting()));
Map<Kind, Integer> minutes = september.stream()
.collect(Collectors.groupingBy(Repair::kind, () -> new EnumMap<>(Kind.class),
Collectors.summingInt(Repair::minutes)));
System.out.printf("%-11s %5s %8s%n", "Kind", "Count", "Minutes");
for (Kind k : counts.keySet()) {
System.out.printf("%-11s %5d %8d%n", k, counts.get(k), minutes.get(k));
}
}
}FLAT tickets: [502, 504, 509] Kind Count Minutes FLAT 3 60 BRAKES 2 80 GEARS 1 60 WHEEL_TRUE 1 40 TUNE_UP 1 80
What this code does
The first groupingBy keeps each bucket as a list, so the flat-tire bucket lists tickets 502, 504 and 509. The next two add an EnumMap supplier and a downstream collector, counting and summingInt, so each bucket becomes a number and the table prints in the order the Kind constants are declared. That is Odile's whole monthly table from one pass over the data for each column.
Two summaries in one pass is possible too. Collectors.teeing(c1, c2, merger), added in Java 12, sends every element to two collectors and combines their results, which gives count and total minutes together without streaming twice. For several statistics of one number, summarizingInt is simpler. And grouping can nest: groupingBy(Repair::month, groupingBy(Repair::kind, counting())) gives a map of maps, month to kind to count.
import java.util.*;
import java.util.stream.*;
public class Main {
enum Kind { FLAT, BRAKES, GEARS, TUNE_UP }
record Repair(int month, Kind kind, int minutes) { }
record Summary(long count, int minutes) { }
public static void main(String[] args) {
List<Repair> log = List.of(
new Repair(9, Kind.FLAT, 20), new Repair(9, Kind.BRAKES, 45), new Repair(9, Kind.FLAT, 15),
new Repair(10, Kind.FLAT, 20), new Repair(10, Kind.GEARS, 60), new Repair(10, Kind.TUNE_UP, 80),
new Repair(10, Kind.FLAT, 25));
Map<Integer, Summary> perMonth = log.stream().collect(Collectors.groupingBy(
Repair::month, TreeMap::new,
Collectors.teeing(Collectors.counting(), Collectors.summingInt(Repair::minutes), Summary::new)));
perMonth.forEach((m, s) -> System.out.println("Month " + m + ": " + s.count() + " repairs, " + s.minutes() + " min"));
Map<Integer, Map<Kind, Long>> nested = log.stream().collect(Collectors.groupingBy(
Repair::month, TreeMap::new,
Collectors.groupingBy(Repair::kind, () -> new EnumMap<>(Kind.class), Collectors.counting())));
System.out.println(nested);
}
}Month 9: 3 repairs, 80 min
Month 10: 4 repairs, 185 min
{9={FLAT=2, BRAKES=1}, 10={FLAT=2, GEARS=1, TUNE_UP=1}}What this code does
teeing sends each repair to both counting and summingInt, and the Summary record's constructor, passed as Summary::new, merges the two results. The nested groupingBy builds a TreeMap of months, each holding an EnumMap of kinds to counts. Because every map here has a defined order, the printed output is the same on every run and every Java version.
partitioningBy: two buckets
When the key is just true or false, Collectors.partitioningBy(predicate) is the clearer tool. It always returns a map with both keys, false and true, even if one bucket is empty, which groupingBy with a boolean classifier does not promise. Like groupingBy, it takes a downstream collector.
import java.util.*;
import java.util.stream.*;
public class Main {
record Part(String code, int quantity, int reorderAt) {
boolean isLow() { return quantity < reorderAt; }
}
public static void main(String[] args) {
List<Part> parts = List.of(
new Part("TUBE-700x25", 3, 10), new Part("PAD-ROAD", 14, 6),
new Part("CHAIN-11", 2, 4), new Part("BELL", 25, 5), new Part("CABLE-BRAKE", 8, 8));
Map<Boolean, List<String>> split = parts.stream().collect(Collectors.partitioningBy(
Part::isLow, Collectors.mapping(Part::code, Collectors.toList())));
System.out.println("Low: " + split.get(true));
System.out.println("Fine: " + split.get(false));
Map<Boolean, Long> none = parts.stream().collect(Collectors.partitioningBy(p -> p.quantity() > 100, Collectors.counting()));
System.out.println("Over 100 in stock: " + none);
}
}Low: [TUBE-700x25, CHAIN-11]
Fine: [PAD-ROAD, BELL, CABLE-BRAKE]
Over 100 in stock: {false=5, true=0}What this code does
partitioningBy splits the parts into low and fine, and the downstream mapping collector keeps only the codes instead of whole records. CABLE-BRAKE has exactly its reorder level, so the strict less-than test counts it as fine. The second partition shows that both keys are present even when no part has more than 100 in stock.
toMap and the duplicate-key trap
Collectors.toMap(keyFunction, valueFunction) builds a map with one entry per element. If two elements produce the same key, the two-argument form throws IllegalStateException with a message naming the duplicate key, because it cannot know which value you want. The three-argument form takes a merge function that decides: keep the first, keep the last, or combine the two, such as adding quantities. The four-argument form also chooses the map type. Duplicate keys are common in real exports, so the safe habit is to always think about the merge.
import java.util.*;
import java.util.stream.*;
public class Main {
record Sale(String code, int quantity) { }
public static void main(String[] args) {
List<Sale> sales = List.of(new Sale("TUBE-700x25", 2), new Sale("BELL", 1), new Sale("TUBE-700x25", 1));
Map<String, Integer> units = sales.stream().collect(Collectors.toMap(Sale::code, Sale::quantity));
System.out.println(units);
}
}What this code does
Two sales share the code TUBE-700x25, so the two-argument toMap does not know which quantity to keep and throws IllegalStateException. The message names the duplicate key and both values, which makes the cause easy to find. The fix is to pass a merge function, as the next example does.
$ javac Main.java
$ java Main
Exception in thread "main" java.lang.IllegalStateException: Duplicate key TUBE-700x25 (attempted merging values 2 and 1)
at java.base/java.util.stream.Collectors.duplicateKeyException(Collectors.java:135)
at java.base/java.util.stream.Collectors.lambda$uniqKeysMapAccumulator$1(Collectors.java:182)
at java.base/java.util.stream.ReduceOps$3ReducingSink.accept(ReduceOps.java:169)
at java.base/java.util.AbstractList$RandomAccessSpliterator.forEachRemaining(AbstractList.java:722)
at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:509)
at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:499)
at java.base/java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:921)
at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
at java.base/java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:682)
at Main.main(Main.java:9)import java.util.*;
import java.util.stream.*;
public class Main {
record Sale(String code, int quantity) { }
record Price(String code, long cents, String asOf) { }
public static void main(String[] args) {
List<Sale> sales = List.of(new Sale("TUBE-700x25", 2), new Sale("BELL", 1), new Sale("TUBE-700x25", 1));
Map<String, Integer> units = sales.stream()
.collect(Collectors.toMap(Sale::code, Sale::quantity, Integer::sum, TreeMap::new));
System.out.println("Units per code: " + units);
List<Price> prices = List.of(new Price("BELL", 600, "2027-03"), new Price("BELL", 650, "2027-09"),
new Price("CHAIN-11", 2499, "2027-01"));
Map<String, Long> latest = prices.stream()
.collect(Collectors.toMap(Price::code, Price::cents, (older, newer) -> newer, TreeMap::new));
System.out.println("Latest prices: " + latest);
}
}Units per code: {BELL=1, TUBE-700x25=3}
Latest prices: {BELL=650, CHAIN-11=2499}What this code does
The merge function Integer::sum adds the quantities of duplicate codes, so the tubes total 3. In the price list, the merge function (older, newer) -> newer keeps the later of two prices, which works because the list is in date order. Passing TreeMap::new as the fourth argument gives a sorted, predictable map for printing.
| Collector | Result | Typical use in a report |
|---|---|---|
| toList(), toSet(), toCollection(...) | a collection | the elements themselves |
| joining(sep, prefix, suffix) | a String | a line of codes or names |
| counting() | Long | how many in each group |
| summingInt / summingLong | Integer / Long | total minutes, total cents |
| averagingInt | Double | average repair time |
| summarizingInt | IntSummaryStatistics | count, sum, min, max and average at once |
| mapping(f, downstream) | whatever downstream gives | keep only one field of each element |
| groupingBy(key, mapFactory, downstream) | Map | a table by category |
| partitioningBy(test, downstream) | Map<Boolean, ...> | two groups such as low and fine |
| toMap(key, value, merge, mapFactory) | Map | one value per key |
| teeing(c1, c2, merger) | a combined value | two summaries in one pass |
After the session Hamza rewrote Odile's spreadsheet chore as a dozen lines: one groupingBy with an EnumMap and teeing for count and minutes. Ingrid's one comment on his pull request was about order. "Never print a HashMap in a report," she wrote. "Ask for the order you mean."
Try it yourself
Units sold per supplier
Use groupingBy with a TreeMap and summingInt to total the units sold for each supplier.
The program should print {Kessler=3, Velotek=5}.
import java.util.*;
import java.util.stream.*;
public class Main {
record Sale(String code, String supplier, int quantity) { }
public static void main(String[] args) {
List<Sale> sales = List.of(
new Sale("TUBE-700x25", "Velotek", 2), new Sale("BELL", "Kessler", 1),
new Sale("PAD-ROAD", "Velotek", 2), new Sale("CHAIN-11", "Kessler", 2),
new Sale("TUBE-700x25", "Velotek", 1));
Map<String, Integer> totals = new TreeMap<>(); // replace with a collector
System.out.println(totals);
}
}Try it yourself
Bikes by type
Each rental bike has a code such as CITY-2; the type is the part before the dash. Use groupingBy with a TreeMap and Collectors.mapping to list the numbers of each type joined with commas.
The program should print CARGO: 1, CITY: 1,2,3,4 and TANDEM: 1, one per line.
import java.util.*;
import java.util.stream.*;
public class Main {
public static void main(String[] args) {
List<String> fleet = List.of("CITY-1", "CITY-2", "CARGO-1", "CITY-3", "TANDEM-1", "CITY-4");
Map<String, String> byType = new TreeMap<>(); // build this with a collector
byType.forEach((type, numbers) -> System.out.println(type + ": " + numbers));
}
}Common mistakes
MistakePrinting the map from a plain groupingBy in a report.
InsteadPass TreeMap::new, or an EnumMap supplier for enum keys, so the order is defined.
MistakeStreaming the data twice to get a count and a total.
InsteadUse teeing, or summarizingInt for several statistics of one number.
MistakeUsing toMap without thinking about duplicate keys.
InsteadPass a merge function that says how to combine or choose between duplicates.
MistakeUsing groupingBy with a boolean key and expecting both keys.
InsteadUse partitioningBy, which always has both true and false.
MistakeKeeping whole records in groups when only one field is needed.
InsteadUse Collectors.mapping as the downstream collector.
Summary and key terms
- A collector tells collect how to turn a stream into a result.
- Collectors.toList, toSet and toCollection gather elements; joining builds a string; counting, summingInt, averagingInt and summarizingInt produce numbers. groupingBy sorts elements into buckets by a key, and its downstream collector summarizes each bucket; it can nest, and a map factory such as TreeMap::new or an EnumMap supplier gives a defined order, which a plain groupingBy's HashMap does not. partitioningBy splits by a predicate and always has both keys. toMap builds one entry per element and throws IllegalStateException on a duplicate key unless given a merge function. teeing sends each element to two collectors and merges their results. mapping applies a function inside a group.
- Collector
- A recipe that collect follows to build a result from a stream.
- Downstream collector
- The collector groupingBy or partitioningBy applies to each bucket.
- groupingBy
- A collector that groups elements into a map by a key.
- partitioningBy
- A collector that splits elements into a map with keys true and false.
- Merge function
- The function toMap uses to combine two values that have the same key.
- teeing
- A collector that feeds every element to two collectors and merges their results.
- EnumMap
- A map with enum keys, kept in the order the constants are declared.
- IntSummaryStatistics
- An object holding the count, sum, minimum, maximum and average of int values.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Which collector counts repairs of each kind?
Show answer
groupingBy(Repair::kind, counting()).
Why pass TreeMap::new to groupingBy in a report?
Show answer
So the keys print in sorted order instead of an undefined order.
What does toMap do with two elements that have the same key and no merge function?
Show answer
It throws IllegalStateException.
When is partitioningBy better than groupingBy?
Show answer
When the key is a true or false test; it always has both keys.
How do you get a count and a total in one pass?
Show answer
Collectors.teeing(counting(), summingInt(...), merger), or summarizingInt.
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.