Streams

Feb 25, 2026

📄 Contents

␡

⎙ Print

< Back Page 9 of 13 Next >

This chapter is from the book 

Core Java, Volume II: Advanced Features, 14th Edition

Learn More Buy

1.9. Collectors

For collecting stream elements to another target, there is a convenient collect method that takes an instance of the Collector interface. A collector is an object that accumulates elements and produces a result. The Collectors class provides a large number of factory methods for common collectors.

Suppose you want to collect all strings in a stream by concatenating them. You can call

String result = stream.collect(Collectors.joining());

If you want a delimiter between elements, pass it to the joining method:

String result = stream.collect(Collectors.joining(", "));

If your stream contains objects other than strings, you need to first convert them to strings, like this:

String result = stream.map(Object::toString).collect(Collectors.joining(", "));

If you want to reduce the stream results to a sum, count, average, maximum, or minimum, use one of the summarizing(Int|Long|Double) methods. These methods take a function that maps the stream objects to numbers and yield a result of type (Int|Long|Double)SummaryStatistics, simultaneously computing the sum, count, average, maximum, and minimum.

IntSummaryStatistics summary = stream.collect(
    Collectors.summarizingInt(String::length));
double averageWordLength = summary.getAverage();
double maxWordLength = summary.getMax();

Note that you are not calling the joining and summarizingInt methods on a stream. These are static methods of the Collectors class. They yield instances of Collector which you pass to the collect method of the Stream interface.

The joining collector yields a string, and the summarizing collectors yield four numbers. However, most collectors collect values in data structures, as you will see in the following sections.

The example program in Listing 1.5 shows how to collect elements from a stream.

Listing 1.4 v2ch01/collecting/CollectingResults.java

package v2ch01.collecting;

import module java.base;

class CollectingResults {
    void main() throws Exception {
        // Turning a stream into an iterator
        Iterator<Integer> iter = Stream.iterate(0, n -> n + 1).limit(10).iterator();
        while (iter.hasNext())
            IO.println(iter.next());

        Object[] numbers = Stream.iterate(0, n -> n + 1).limit(10).toArray();
        IO.println("Object array: " + numbers + " " + Arrays.toString(numbers));
        // Note it's an Object[] array

        try {
            var number = (Integer) numbers[0]; // OK
            IO.println("number: " + number);
            IO.println("The following statement throws an exception:");
            var _ = (Integer[]) numbers; // Throws exception
        }
        catch (ClassCastException e) {
            IO.println(e);
        }

        Integer[] numbers3 = Stream.iterate(0, n -> n + 1).limit(10).toArray(Integer[]::new);
        IO.println("Integer array: " + numbers3 + " " + Arrays.toString(numbers3));
        // Note it's an Integer[] array

        String result = noVowels().limit(10).collect(Collectors.joining());
        IO.println("Joining: " + result);
        result = noVowels().limit(10).collect(Collectors.joining(", "));
        IO.println("Joining with commas: " + result);

        IntSummaryStatistics summary = noVowels()
                .collect(Collectors.summarizingInt(String::length));
        double averageWordLength = summary.getAverage();
        double maxWordLength = summary.getMax();
        IO.println("Average word length: " + averageWordLength);
        IO.println("Max word length: " + maxWordLength);
        IO.println("forEach:");
        noVowels().limit(10).forEach(IO::println);
    }

    Stream<String> noVowels() throws IOException {
        String contents = Files.readString(Path.of("gutenberg", "alice30.txt"));
        Stream<String> words = Stream.of(contents.split("\\PL+"));
        return words.map(s -> s.replaceAll("[aeiouAEIOU]", ""));
    }

    <T> void show(String label, Set<T> set) {
        IO.print(label + ": " + set.getClass().getName());
        IO.println("["
            + set.stream().limit(10).map(Object::toString).collect(Collectors.joining(", "))
            + "]");
    }
}

java.util.stream.Collectors8

static Collector<CharSequence,?,String> joining()
static Collector<CharSequence,?,String> joining(CharSequence delimiter)
static Collector<CharSequence,?,String> joining(CharSequence delimiter, CharSequence prefix, CharSequence suffix)

yield a collector that joins strings. The delimiter is placed between strings, and the prefix and suffix before the first and after the last string. When not specified, these are empty.
static <T> Collector<T,?,IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper)
static <T> Collector<T,?,LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper)
static <T> Collector<T,?,DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper)

yield collectors that produce an (Int|Long|Double)SummaryStatistics object, from which you can obtain the count, sum, average, maximum, and minimum of the results of applying mapper to each element.

1.9.1. Collecting into Collections

Before the toList method was added in Java 16, you had to use the collector produced by Collectors.toList():

List<String> result = stream.collect(Collectors.toList());

Similarly, here is how you can collect stream elements into a set:

Set<String> result = stream.collect(Collectors.toSet());

These calls give you a list or set, but you cannot make any further assumptions. The collection might not be mutable, serializable, or thread-safe. If you want to control which kind of collection you get, use the following call instead:

TreeSet<String> result = stream.collect(Collectors.toCollection(TreeSet::new));

The example program in Listing 1.5 shows how to place stream elements into a collection.

Listing 1.5 v2ch01/collecting/CollectingResults.java

package v2ch01.collecting;

import module java.base;

class CollectingResults {
    void main() throws Exception {
        // Turning a stream into an iterator
        Iterator<Integer> iter = Stream.iterate(0, n -> n + 1).limit(10).iterator();
        while (iter.hasNext())
            IO.println(iter.next());

        Object[] numbers = Stream.iterate(0, n -> n + 1).limit(10).toArray();
        IO.println("Object array: " + numbers + " " + Arrays.toString(numbers));
        // Note it's an Object[] array

        try {
            var number = (Integer) numbers[0]; // OK
            IO.println("number: " + number);
            IO.println("The following statement throws an exception:");
            var _ = (Integer[]) numbers; // Throws exception
        }
        catch (ClassCastException e) {
            IO.println(e);
        }

        Integer[] numbers3 = Stream.iterate(0, n -> n + 1).limit(10).toArray(Integer[]::new);
        IO.println("Integer array: " + numbers3 + " " + Arrays.toString(numbers3));
        // Note it's an Integer[] array

        String result = noVowels().limit(10).collect(Collectors.joining());
        IO.println("Joining: " + result);
        result = noVowels().limit(10).collect(Collectors.joining(", "));
        IO.println("Joining with commas: " + result);

        IntSummaryStatistics summary = noVowels()
                .collect(Collectors.summarizingInt(String::length));
        double averageWordLength = summary.getAverage();
        double maxWordLength = summary.getMax();
        IO.println("Average word length: " + averageWordLength);
        IO.println("Max word length: " + maxWordLength);
        IO.println("forEach:");
        noVowels().limit(10).forEach(IO::println);
    }

    Stream<String> noVowels() throws IOException {
        String contents = Files.readString(Path.of("gutenberg", "alice30.txt"));
        Stream<String> words = Stream.of(contents.split("\\PL+"));
        return words.map(s -> s.replaceAll("[aeiouAEIOU]", ""));
    }

    <T> void show(String label, Set<T> set) {
        IO.print(label + ": " + set.getClass().getName());
        IO.println("["
            + set.stream().limit(10).map(Object::toString).collect(Collectors.joining(", "))
            + "]");
    }
}

java.util.stream.Collectors8

static <T> Collector<T,?,List<T>> toList()
static <T> Collector<T,?,List<T>> toUnmodifiableList()10
static <T> Collector<T,?,Set<T>> toSet()
static <T> Collector<T,?,Set<T>> toUnmodifiableSet()10

yield collectors that collect elements in a list or set.
static <T,C extends Collection<T>> Collector<T,?,C> toCollection(Supplier<C> collectionFactory)

yields a collector that collects elements into an arbitrary collection. Pass a constructor reference such as TreeSet::new.

1.9.2. Collecting into Maps

Suppose you have a Stream<Person> and want to collect the elements into a map so that later you can look up people by their ID. Call Collectors.toMap with two functions that produce the map's keys and values. For example,

public record Person(int id, String name) {}
. . .
Map<Integer, String> idToName = people.collect(
    Collectors.toMap(Person::id, Person::name));

In the common case when the values should be the actual elements, use Function.identity() for the second function.

Map<Integer, Person> idToPerson = people.collect(
    Collectors.toMap(Person::id, Function.identity()));

If there is more than one element with the same key, there is a conflict, and the collector will throw an IllegalStateException. You can override that behavior by supplying a third function that resolves the conflict and determines the value for the key, given the existing and the new value. Your function could return the existing value, the new value, or a combination of them.

Here, we construct a map that contains, for each language in the available locales, as key its name in your default locale (such as "German"), and as value its localized name (such as "Deutsch").

Map<String, String> languageNames = Locale.availableLocales().collect(
    Collectors.toMap(
        Locale::getDisplayLanguage,
        loc -> loc.getDisplayLanguage(loc),
        (existingValue, newValue) -> existingValue));

We don't care that the same language might occur twice (for example, German in Germany and in Switzerland), so we just keep the first entry.

Now suppose we want to know all languages in a given country. Then we need a Map<String, Set<String>>. For example, the value for "Switzerland" is the set [French, German, Italian]. At first, we store a singleton set for each language. Whenever a new language is found for a given country, we form the union of the existing and the new set.

Map<String, Set<String>> countryLanguageSets = Locale.availableLocales().collect(
    Collectors.toMap(
        Locale::getDisplayCountry,
        l -> Collections.singleton(l.getDisplayLanguage()),
        (a, b) -> { // Union of a and b
            var union = new HashSet<String>(a);
            union.addAll(b);
            return union;
        }));

You will see a simpler way of obtaining this map in the next section.

If you want a TreeMap, supply the constructor as the fourth argument. You must provide a merge function. Here is one of the examples from the beginning of the section, now yielding a TreeMap:

Map<Integer, Person> idToPerson = people.collect(
    Collectors.toMap(
        Person::id,
        Function.identity(),
        (existingValue, newValue) -> { throw new IllegalStateException(); },
        TreeMap::new));

The program in Listing 1.6 gives examples of collecting stream results into maps.

Listing 1.6 v2ch01/collecting/CollectingIntoMaps.java

package v2ch01.collecting;

import module java.base;

record Person(int id, String name) {}

class CollectingIntoMaps {
    void main() throws Exception {
        Map<Integer, String> idToName = people()
                .collect(Collectors.toMap(Person::id, Person::name));
        IO.println("idToName: " + idToName);

        Map<Integer, Person> idToPerson = people()
                .collect(Collectors.toMap(Person::id, Function.identity()));
        IO.println("idToPerson: " + idToPerson.getClass().getName() + idToPerson);

        idToPerson = people().collect(
                Collectors.toMap(Person::id, Function.identity(), (_, _) -> {
                    throw new IllegalStateException();
                }, TreeMap::new));
        IO.println("idToPerson: " + idToPerson.getClass().getName() + idToPerson);

        Map<String, String> languageNames = Locale.availableLocales()
                .collect(Collectors.toMap(Locale::getDisplayLanguage,
                        l -> l.getDisplayLanguage(l),
                        (existingValue, _) -> existingValue));
        IO.println("languageNames: " + languageNames);

        Map<String, Set<String>> countryLanguageSets = Locale.availableLocales()
                .collect(Collectors.toMap(Locale::getDisplayCountry,
                        l -> Set.of(l.getDisplayLanguage()), (a, b) -> { // union of a and b
                            Set<String> union = new HashSet<>(a);
                            union.addAll(b);
                            return union;
                        }));
        IO.println("countryLanguageSets: " + countryLanguageSets);
    }

    static Stream<Person> people() {
        return Stream.of(new Person(1001, "Peter"), new Person(1002, "Paul"),
                new Person(1003, "Mary"));
    }    
}

java.util.stream.Collectors8

static <T,K,U> Collector<T,?,Map<K,U>> toMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper)
static <T,K,U> Collector<T,?,Map<K,U>> toMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper, BinaryOperator mergeFunction)
static <T,K,U,M extends Map<K,U>> Collector<T,?,M> toMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper, BinaryOperator mergeFunction, Supplier<M> mapSupplier)
static <T,K,U> Collector<T,?,Map<K,U>> toUnmodifiableMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper)10
static <T,K,U> Collector<T,?,Map<K,U>> toUnmodifiableMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper, BinaryOperator mergeFunction)10
static <T,K,U> Collector<T,?,ConcurrentMap<K,U>> toConcurrentMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper)
static <T,K,U> Collector<T,?,ConcurrentMap<K,U>> toConcurrentMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper, BinaryOperator mergeFunction)
static <T,K,U,M extends ConcurrentMap<K,U>> Collector<T,?,M> toConcurrentMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends U> valueMapper, BinaryOperator mergeFunction, Supplier<M> mapSupplier)

yield a collector that produces a map, unmodifiable map, or concurrent map. The keyMapper and valueMapper functions are applied to each collected element, yielding a key/value entry of the resulting map. By default, an IllegalStateException is thrown when two elements give rise to the same key. You can instead supply a mergeFunction that merges values with the same key. By default, the result is a HashMap or ConcurrentHashMap. You can instead supply a mapSupplier that yields the desired map instance.

1.9.3. Grouping and Partitioning

In the preceding section, you saw how to collect all languages in a given country. But the process was a bit tedious. You had to generate a singleton set for each map value and then specify how to merge the existing and new values. Forming groups of values with the same characteristic is very common, so the groupingBy method supports it directly.

Let’s look at the problem of grouping locales by country. First, form this map:

Map<String, List<Locale>> countryToLocales = Locale.availableLocales().collect(
    Collectors.groupingBy(Locale::getCountry));

The function Locale::getCountry is the classifier function of the grouping. You can now look up all locales for a given country code, for example

List<Locale> swissLocales = countryToLocales.get("CH");
    // Yields locales de_CH, fr_CH, it_CH, and maybe more

When the classifier function is a predicate function (that is, a function returning a boolean value), the stream elements are partitioned into two lists: those where the function returns true and the complement. In this case, it is more efficient to use partitioningBy instead of groupingBy. For example, here we split all locales into those that use English and all others:

Map<Boolean, List<Locale>> englishAndOtherLocales = Locale.availableLocales().collect(
    Collectors.partitioningBy(l -> l.getLanguage().equals("en")));
List<Locale> englishLocales = englishAndOtherLocales.get(true);

java.util.stream.Collectors8

static <T,K> Collector<T,?,Map<K,List<T>>> groupingBy(Function<? super T,? extends K> classifier)
static <T,K> Collector<T,?,ConcurrentMap<K,List<T>>> groupingByConcurrent(Function<? super T,? extends K> classifier)

yield a collector that produces a map or concurrent map whose keys are the results of applying classifier to all collected elements, and whose values are lists of elements with the same key.
static <T> Collector<T,?,Map<Boolean,List<T>>> partitioningBy(Predicate<? super T> predicate)

yields a collector that produces a map whose keys are true/false, and whose values are lists of the elements that fulfill/do not fulfill the predicate.

1.9.4. Downstream Collectors

The groupingBy method yields a map whose values are lists. If you want to process those lists in some way, supply a downstream collector. For example, if you want sets instead of lists, you can use the Collectors.toSet collector that you saw in the preceding section:

Map<String, Set<Locale>> countryToLocaleSet = Locale.availableLocales().collect(
    groupingBy(Locale::getCountry, toSet()));

You can also apply groupingBy twice:

Map<String, Map<String, List<Locale>>> countryAndLanguageToLocale =
    Locale.availableLocales().collect(
        groupingBy(Locale::getCountry,
            groupingBy(Locale::getLanguage)));

Then countryAndLanguageToLocale.get("IN").get("hi") is a list of the Hindi locales in India. (There are several variants.)

Several collectors are provided for reducing collected elements to numbers:

counting produces a count of the collected elements. For example,

Map<String, Long> countryToLocaleCounts = Locale.availableLocales().collect(
    groupingBy(Locale::getCountry, counting()));

counts how many locales there are for each country.

summing(Int|Long|Double) and averaging(Int|Long|Double) apply a provided function to the downstream elements and produce the sum or average of the function's results. For example,
```
public record City(String name, String state, int population) {}
. . .
Map<String, Integer> stateToCityPopulation = cities.collect(
 groupingBy(City::state, averagingInt(City::population)));
```
computes the average of populations per state in a stream of cities.

maxBy and minBy take a comparator and produce maximum and minimum of the downstream elements. For example,

Map<String, Optional<City>> stateToLargestCity = cities.collect(
    groupingBy(City::state,
        maxBy(Comparator.comparing(City::population))));

produces the largest city per state.

The collectingAndThen collector adds a final processing step behind a collector. For example, if you want to know how many distinct results there are, collect them into a set and then compute the size:

Map<Character, Integer> stringCountsByStartingLetter = strings.collect(
    groupingBy(s -> s.charAt(0),
        collectingAndThen(toSet(), Set::size)));

The mapping collector does the opposite. It applies a function to each collected element and passes the results to a downstream collector.

Map<Character, Set<Integer>> stringLengthsByStartingLetter = strings.collect(
    groupingBy(s -> s.charAt(0),
        mapping(String::length, toSet())));

Here, we group strings by their first character. Within each group, we produce the lengths and collect them in a set.

The mapping method also yields a nicer solution to a problem from the preceding section—gathering a set of all languages in a country.

Map<String, Set<String>> countryToLanguages = Locale.availableLocales().collect(
    groupingBy(Locale::getDisplayCountry,
        mapping(Locale::getDisplayLanguage,
            toSet())));

There is a flatMapping method as well, for use with functions that return streams.

If the grouping or mapping function has return type int, long, or double, you can collect elements into a summary statistics object, as discussed in Section 1.8. For example,

Map<String, IntSummaryStatistics> stateToCityPopulationSummary = cities.collect(
    groupingBy(City::state,
        summarizingInt(City::population)));

Then you can get the sum, count, average, minimum, and maximum of the function values from the summary statistics objects of each group.

The filtering collector applies a filter to each group, for example:

Map<String, Set<City>> largeCitiesByState
    = cities.collect(
        groupingBy(City::state,
            filtering(c -> c.population() > 500000,
                toSet()))); // States without large cities have empty sets

Finally, you can use the teeing collector to branch into two downstream collections. This is useful whenever you need to compute more than one result from a stream. Suppose you want to collect city names and also compute their average population. You can't read a stream twice, but teeing lets you carry out two computations. Specify two downstream collectors and a function that combines the results.

record Pair<S, T>(S first, T second) {}
Pair<List<String>, Double> result = cities.filter(c -> c.state().equals("NV"))
    .collect(teeing(
        mapping(City::name, toList()), // First downstream collector
        averagingDouble(City::population), // Second downstream collector
        (list, avg) -> new Pair(list,  avg))); // Combining function

Composing collectors is powerful, but it can lead to very convoluted expressions. The best use is with groupingBy or partitioningBy to process the “downstream” map values. Otherwise, simply apply methods such as map, reduce, count, max, or min directly on streams.

The example program in Listing 1.7 demonstrates downstream collectors.

Listing 1.7 v2ch01/collecting/DownstreamCollectors.java

package v2ch01.collecting;

import static java.util.stream.Collectors.*;

import module java.base;

record City(String name, String state, int population) {}

class DownstreamCollectors {

    void main() throws Exception {
        Map<String, Set<Locale>> countryToLocaleSet = Locale.availableLocales()
                .collect(groupingBy(Locale::getCountry, toSet()));
        IO.println("countryToLocaleSet: " + countryToLocaleSet);

        Map<String, Map<String, List<Locale>>> countryAndLanguageToLocale = Locale
                .availableLocales()
                .collect(groupingBy(Locale::getCountry, groupingBy(Locale::getLanguage)));
        IO.println(
            "Hindi locales in India: " + countryAndLanguageToLocale.get("IN").get("hi"));

        Map<String, Long> countryToLocaleCounts = Locale.availableLocales()
                .collect(groupingBy(Locale::getCountry, counting()));
        IO.println("countryToLocaleCounts: " + countryToLocaleCounts);

        Stream<City> cities = readCities("v2ch01/cities.txt");
        Map<String, Integer> stateToCityPopulation = cities
                .collect(groupingBy(City::state, summingInt(City::population)));
        IO.println("stateToCityPopulation: " + stateToCityPopulation);

        cities = readCities("v2ch01/cities.txt");
        Map<String, Optional<String>> stateToLongestCityName = cities.collect(groupingBy(
            City::state, mapping(City::name, maxBy(Comparator.comparing(String::length)))));
        IO.println("stateToLongestCityName: " + stateToLongestCityName);

        Map<String, Set<String>> countryToLanguages = Locale.availableLocales()
                .collect(groupingBy(Locale::getDisplayCountry,
                    mapping(Locale::getDisplayLanguage, toSet())));
        IO.println("countryToLanguages: " + countryToLanguages);

        cities = readCities("v2ch01/cities.txt");
        Map<String, IntSummaryStatistics> stateToCityPopulationSummary = cities
                .collect(groupingBy(City::state, summarizingInt(City::population)));
        IO.println(stateToCityPopulationSummary.get("NY"));

        cities = readCities("v2ch01/cities.txt");
        Map<String, String> stateToCityNames = cities.collect(groupingBy(City::state,
            reducing("", City::name, (s, t) -> s.length() == 0 ? t : s + ", " + t)));

        cities = readCities("v2ch01/cities.txt");
        stateToCityNames = cities
                .collect(groupingBy(City::state, mapping(City::name, joining(", "))));
        IO.println("stateToCityNames: " + stateToCityNames);

        cities = readCities("v2ch01/cities.txt");
        record Pair<S, T>(S first, T second) {
        }
        Pair<List<String>, Double> result = cities.filter(c -> c.state().equals("NV")).collect(
            teeing(mapping(City::name, toList()), averagingDouble(City::population),
                (names, avg) -> new Pair<>(names, avg)));
        IO.println(result);
    }

    Stream<City> readCities(String filename) throws IOException {
        return Files.lines(Path.of(filename)).map(l -> l.split(", "))
                .map(a -> new City(a[0], a[1], Integer.parseInt(a[2])));
    }
}

java.util.stream.Collectors8

public static <T,K,A,D> Collector<T,?,Map<K,D>> groupingBy(Function<? super T,? extends K> classifier, Collector<? super T,A,D> downstream)

yields a collector that produces a map. The keys are the results of applying classifier to all collected elements. The values are the results of collecting elements with the same key, using the downstream collector.
static <T> Collector<T,?,Long> counting()

yields a collector that counts the collected elements.
static <T> Collector<T,?,Integer> summingInt(ToIntFunction<? super T> mapper)
static <T> Collector<T,?,Long> summingLong(ToLongFunction<? super T> mapper)
static <T> Collector<T,?,Double> summingDouble(ToDoubleFunction<? super T> mapper)

yield a collector that computes the sum of the results of applying mapper to the collected elements.
static <T> Collector<T,?,Optional<T>> maxBy(Comparator<? super T> comparator)
static <T> Collector<T,?,Optional<T>> minBy(Comparator<? super T> comparator)

yield a collector that computes the maximum or minimum of the collected elements, using the ordering specified by comparator.
static <T,A,R,RR> Collector<T,A,RR> collectingAndThen(Collector<T,A,R> downstream, Function<R,RR> finisher)

yields a collector that sends elements to the downstream collector and then applies the finisher function to its result.
static <T,U,A,R> Collector<T,?,R> mapping(Function<? super T,? extends U> mapper, Collector<? super U,A,R> downstream)

yields a collector that calls mapper on each element and passes the results to the downstream collector.
static <T,U,A,R> Collector<T,?,R> flatMapping(Function<? super T,? extends Stream<? extends U>> mapper, Collector<? super U,A,R> downstream)

yields a collector that calls mapper on each element and passes the elements of the results to the downstream collector.
static <T,A,R> Collector<T,?,R> filtering(Predicate<? super T> predicate, Collector<? super T,A,R> downstream)

yields a collector that passes the elements fulfilling the predicate to the downstream collector.

1.9.5. Implementing Collectors

In the collection process, a collector accumulates incoming stream elements in an internal data structure called a “result container.” Each collector can choose a suitable result container type. If the stream is parallel, multiple result containers are filled concurrently and then merged. After accumulation and merging, the collector can optionally transform the final result container into another object that is the collection result.

Specifically, a Collector must implement four methods, each of which yields a function object:

Supplier<A> supplier() supplies a result container of type A.
BiConsumer<A,T> accumulator() accumulates a stream element of type T into a result container.
BinaryOperator<A> combiner() combines two result containers into one.
Function<A, R> finisher() transforms the final result container into the result of type R.

Let’s look at the function objects of the Collectors.toList() collector:

The supplier is a function yielding an empty ArrayList<T> or simply ArrayList<T>::new.
The accumulator is (rc, t) -> rc.add(t) or List::add. (That method expression is why the result container is the first parameter.)
The combiner concatenates two lists: (rc1, rc2) -> { rc1.addAll(rc2); return rc1; }.
The finisher does nothing (which is the most common case).

The characteristics method of a collector returns a set of Collector.Characteristics flags that can help the stream with optimizing the collection process. There are three of them:

IDENTITY_FINISH: the finisher need not be called.
UNORDERED: it is ok not to call the accumulator in encounter order.
CONCURRENT: it is safe to call the accumulator from multiple threads on the same result container.

Collectors.joining returns a collector with none of these characteristics. The result container is a StringBuilder. The finisher must convert it into a string. Accumulation order matters. And the result container is not threadsafe.

In contrast, the toConcurrentMap collector has all three characteristics. The result container is a threadsafe ConcurrentHashMap. Insertion order does not matter, and no finishing is needed.

Let’s build a collector that statistically samples elements, accepting them with a given probability. For now, we’ll collect the accepted elements in a list.

Following the Collectors API, let’s make a method that yields the collector:

 <T> Collector<T, List<T>, List<T>> randomSampling(double p) {
    return Collector.of(ArrayList<T>::new,
            (resultContainer, e) -> {
                if (Math.random() < p)
                    resultContainer.add(e);
                },
            (rc1, rc2) -> { rc1.addAll(rc2); return rc1; },
            Function.identity(),
            Collector.Characteristics.IDENTITY_FINISH);
    }

The Collector.of method has five parameters: the four functions and a varargs parameter for the characteristics.

This collector is almost the same as the toList collector, except that the accumulator only stores some of the elements.

Here is how to use it:

Stream<Integer> numbers = . . .;
List<Integer> sampled = numbers.collect(randomSampling(0.05)); // About every 20th element

What if we don't want the accepted elements in a list? Our API should support downstream collectors. Here is how:

<T, A, R> Collector<T, A, R> randomSampling(double p, Collector<T, A, R> downstream) {
        BiConsumer<A, T> downstreamAccumulator = downstream.accumulator();
        return Collector.of(downstream.supplier(),
                (resultContainer, e) -> {
                    if (Math.random() < p)
                        downstreamAccumulator.accept(resultContainer, e);
                    },
                downstream.combiner(),
                downstream.finisher(),
                downstream.characteristics().toArray(Collector.Characteristics[]::new));
    }

Here, downstream is a collector that accepts elements of type T, with a result container of type A, and result type R.

We can reuse the downstream’s supplier, combiner, and finisher, but we must adapt its accumulator, so that only a fraction of the incoming elements are inserted.

Unfortunately, the API leaves something to be desired for this particular use case. I have to turn the downstream’s set of characteristics into an array for the varargs parameter.

The program in Listing 1.8 has the complete example.

Listing 1.8 v2ch01/collecting/ImplementingCollectors.java

package v2ch01.collecting;

import module java.base;

class ImplementingCollectors {
    void main() {
        IO.println(IntStream.range(1, 1000)
            .boxed()
            .parallel()
            .collect(randomSampling(0.05)));
        IO.println(IntStream.range(1, 1000)
            .boxed()
            .parallel()
            .collect(randomSampling(0.05, Collectors.toSet())));
    }

    <T> Collector<T, List<T>, List<T>> randomSampling(double p) {
        return Collector.of(ArrayList<T>::new, 
                (resultContainer, e) -> { 
                    if (Math.random() < p) 
                        resultContainer.add(e); 
                    }, 
                (rc1, rc2) -> { rc1.addAll(rc2); return rc1; },
                Function.identity(), 
                Collector.Characteristics.IDENTITY_FINISH);
    }

    <T, A, R> Collector<T, A, R> randomSampling(double p, Collector<T, A, R> downstream) {
        BiConsumer<A, T> downstreamAccumulator = downstream.accumulator();
        return Collector.of(downstream.supplier(),
                (resultContainer, e) -> { 
                    if (Math.random() < p) 
                        downstreamAccumulator.accept(resultContainer, e); 
                    },
                downstream.combiner(), 
                downstream.finisher(),
                downstream.characteristics().toArray(Collector.Characteristics[]::new));
    }
}

java.util.stream.Collector<T, A, R>8

Supplier<A> supplier()

The function to supply a new result container.
BiConsumer<A,T> accumulator()

The function to incorporate an element from the stream into a result container.
BinaryOperator<A> combiner()

The function to combine two result containers.
Function<A,R> finisher()

The function that turns the final result container into the result of the collector
Set<Collector.Characteristics> characteristics()

The characteristics of this collector.
static <T,A,R> Collector<T,A,R> of(Supplier<A> supplier, BiConsumer<A,T> accumulator, BinaryOperator<A> combiner, Function<A,R> finisher, Collector.Characteristics... characteristics)

yields a collector with the given supplier, accumulator, combiner, finisher, and characteristics.

< Back Page 9 of 13 Next >

🔖 Save To Your Account

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Email Address

Streams

This chapter is from the book

This chapter is from the book

This chapter is from the book 

1.9. Collectors

Listing 1.4 v2ch01/collecting/CollectingResults.java

1.9.1. Collecting into Collections

Listing 1.5 v2ch01/collecting/CollectingResults.java

1.9.2. Collecting into Maps

Listing 1.6 v2ch01/collecting/CollectingIntoMaps.java

1.9.3. Grouping and Partitioning

1.9.4. Downstream Collectors

Listing 1.7 v2ch01/collecting/DownstreamCollectors.java

1.9.5. Implementing Collectors

Listing 1.8 v2ch01/collecting/ImplementingCollectors.java

InformIT Promotional Mailings & Special Offers