groupingBy and partitioningBy in depth

For this lesson, we'll focus on the Collector API side: the three groupingBy overloads, map factories, downstream combinations, concurrent grouping, null classifier behavior and partitioningBy details. The collections module already teaches the broader grouping pattern in Grouping and partitioning, including manual computeIfAbsent. Here we'll use different order-report examples and go deeper into collector composition.

01Picture it first: chutes with different machines inside

Picture a fulfillment center with three sorting chutes. The label reader sends each order to a customer, status or month chute. Inside each chute, you choose the machine: a tray for orders, a counter, a revenue meter, a set of SKUs, or a max tracker.

The classifier and downstream collector are separate decisions. The classifier chooses the map key; the downstream chooses the value type. Once that clicks, the overloads read like a small language for reports.

Fig. 1

Orders flow through classifiers for customer, status and month, then downstream collectors turn each bucket into lists, counts, totals or best orders

Notice the map factory sitting outside the buckets. It does not change which orders belong together. It changes the map that holds the groups, which is why ordering requirements belong in the overload choice.

02The three groupingBy overloads under the hood

The one-argument overload is the default shape: Map<K, List<T>>. Use it when the caller really needs the original objects by key. Do not use it as a habit when the caller only needs a count or total.

import java.time.YearMonth;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Collectors;

enum Status { NEW, PAID, SHIPPED, CANCELLED }
record Order(String id, String customerId, Status status, YearMonth month, int cents) { }

public class GroupingOverloadsDemo {
    public static void main(String[] args) {
        List<Order> orders = List.of(
                new Order("o-1", "c-2", Status.PAID, YearMonth.of(2026, 10), 1200),
                new Order("o-2", "c-1", Status.NEW, YearMonth.of(2026, 10), 700),
                new Order("o-3", "c-2", Status.PAID, YearMonth.of(2026, 11), 400));

        Map<String, List<Order>> byCustomer = orders.stream()
                .collect(Collectors.groupingBy(Order::customerId));

        Map<Status, Long> countByStatus = orders.stream()
                .collect(Collectors.groupingBy(Order::status, Collectors.counting()));

        Map<YearMonth, Integer> revenueByMonth = orders.stream()
                .collect(Collectors.groupingBy(
                        Order::month,
                        TreeMap::new,
                        Collectors.summingInt(Order::cents)));

        System.out.println(byCustomer.get("c-2").size());
        System.out.println(countByStatus.get(Status.PAID));
        System.out.println(revenueByMonth.keySet());
    }
}

Notice three things:

• The one-argument overload gives lists because no downstream collector was supplied.
• The two-argument overload changes each bucket from List<Order> to Long.
• The three-argument overload makes ordering part of the contract by using TreeMap::new.

If you use the one- or two-argument overload, do not promise HashMap ordering to callers. The API does not guarantee the returned map type. The common implementation may be a HashMap, but tests and APIs should not depend on that.