Collectors والتجميع

Written Explanation

What collect does

collect(collector) is the general terminal operation. A collector describes how to gather elements into a result. The Collectors class (note the s) provides ready-made ones, which you can use as Collectors.toList() or, with import static java.util.stream.Collectors.*;, simply as toList(). The examples below use the full form Collectors. so it is always clear where each method comes from.

For a plain list you can still use toList() on the stream itself (Lesson 1). Use collect when you want a set, a joined string, or a map. For Collectors.toList() (the collector), the Javadoc gives no guarantee about the type or mutability of the list, so do not rely on it being changeable; if you need that, copy into new ArrayList<>(...).

joining works on a stream of strings (it accepts CharSequence elements). It also has a form with a prefix and a suffix: joining(", ", "[", "]").

groupingBy: sorting into boxes

groupingBy takes a classifier: a function that says which group each item belongs to. It returns a Map from each key to a List of the items with that key:

Map<String, List<Person>> byCity = people.stream()
    .collect(Collectors.groupingBy(Person::city));

If three people live in Riyadh, byCity.get("Riyadh") is a list of those three. A key exists only if at least one item had it. On an empty stream the result is an empty map, so a missing category is a missing key, not a zero.

The downstream collector: counting and totalling each box

By default each box holds a list. A second argument, the downstream collector, says what to do with each box instead of listing it:

Map<String, Long> countByCity = people.stream()
    .collect(Collectors.groupingBy(Person::city, Collectors.counting()));

Map<String, Double> revenue = orders.stream()
    .collect(Collectors.groupingBy(Order::category,
                                   Collectors.summingDouble(Order::amount)));

Read the second one aloud: "group the orders by category, and in each group add up the amounts." The types follow directly: counting() gives Long, so the map is Map<String, Long>; summingDouble(...) gives Double, so the map is Map<String, Double>. The Javadoc says counting() returns 0 for no elements and that summingDouble and averagingDouble return 0 for an empty group; both can be affected by NaN values. It also warns that a double sum can vary slightly with the order of the values because of rounding, so do not compare grouped sums with ==.

averagingDouble(f) works the same way, for example the average order amount per category. For whole-number amounts there are summingInt, summingLong, and averagingInt for the same jobs.

Another useful downstream collector is Collectors.mapping, which changes each item before collecting it, for example listing just the names in each city:

Collectors.groupingBy(Person::city, Collectors.mapping(Person::name, Collectors.toList()))

SQL parallel

If you know SQL, read a groupingBy as GROUP BY; if you do not yet, this table is a head start for BEG-050.

The map is not sorted

The Javadoc makes no guarantee about the exact type, mutability, or thread-safety of the map that groupingBy returns; it only promises the static type Map. In practice you should therefore treat the order of the entries as unspecified. When you need stable output, sort when you print. A quick way to see sorted keys is new TreeMap<>(map); for a result ordered by value, use a new stream, as follows. (There is also an overload that takes a map factory such as TreeMap::new when you need a specific type; the Javadoc shows it.)

From totals to a "top N" list

A Map has no sorted, but its entries do: map.entrySet().stream() gives a stream of Map.Entry items, each with getKey() and getValue(). To rank by value:

List<String> top = totals.entrySet().stream()
    .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
    .limit(2)
    .map(e -> e.getKey() + "=" + e.getValue())
    .toList();

Map.Entry.comparingByValue() builds a comparator that orders entries by value; reversed() makes it largest-first. The explicit <String, Double> helps the compiler infer the types when you call reversed(). Note that ties have no special treatment: two customers with the same total can appear in any order unless you add a second sort key with thenComparing.