Collecting Stream Elements into a List in Java

1. Overview

In this tutorial, we'll look at different methods to get a List from a Stream. We'll also discuss the differences among them and when to use which method.

2. Collecting Stream Elements into a List

Getting a List from a Stream is the most used terminal operation of the Stream pipeline. Before Java 16, we used to invoke the Stream.collect() method and pass it to a Collector as an argument to gather the elements into. The Collector itself was created by calling the Collectors.toList() method.

However, there have been change requests for a method to get a List directly from a Stream instance. After the Java 16 release, we can now invoke toList(), a new method directly on the Stream, to get the List. Libraries like StreamEx also provide a convenient way to get a List directly from a Stream.

We can accumulate Stream elements into a List by using:

• Stream.collect(Collectors.toList()): Since Java 8
• Stream.collect(Collectors.toUnmodifiableList()): Since Java 10
• Stream.toList(): Since Java 16

We'll work with the methods in the chronological order of their release.

3. Analyzing the Lists

Let's first create the lists from the methods described in the previous section. After that, let's analyze their properties.

We'll use the following Stream of country codes for all the examples:

Stream.of(Locale.getISOCountries());

3.1. Creating Lists

Now, we'll create a List from the given Stream of country codes using the different methods:

First, let's create a List using Collectors:toList():

List<String> result = Stream.of(Locale.getISOCountries()).collect(Collectors.toList());

After that, let's collect it using Collectors.toUnmodifiableList():

List<String> result = Stream.of(Locale.getISOCountries()).collect(Collectors.toUnmodifiableList());

Here, in these methods, we accumulate the Stream into a List through the Collector interface. This results in extra allocation and copying as we don't work directly with the Stream.

Then, let's repeat the collection with Stream.toList():

List<String> result = Stream.of(Locale.getISOCountries()).toList();

Here, we get the List directly from the Stream, thus preventing extra allocation and copying.

So, using toList() directly on the Stream is more concise, neat, convenient, and optimum when compared to the other two invocations.

3.2. Examining the Accumulated Lists

Let's begin with examining the type of List we created.

Collectors.toList(), collects the Stream elements into an ArrayList:

java.util.ArrayList

Collectors.toUnmodifiableList(), collects the Stream elements into an unmodifiable List.

java.util.ImmutableCollections.ListN

Stream.toList(), collects the elements into an unmodifiable List.

java.util.ImmutableCollections.ListN

Though the current implementation of the Collectors.toList() creates a mutable List, the method's specification itself makes no guarantee on the type, mutability, serializability, or thread-safety of the List.

On the other hand, both Collectors.toUnmodifiableList() and Stream.toList(), produce unmodifiable lists.

This implies that we can do operations like add and sort on the elements of Collectors.toList(), but not on the elements of Collectors.toUnmodifiableList() and Stream.toList(). 

3.3. Allowing Null Elements in the Lists

Although Stream.toList() produces an unmodifiable List, it is still not the same as Collectors.toUnmodifiableList(). This is because Stream.toList() allows the null elements and Collectors.toUnmodifiableList() doesn't allow the null elements. However, Collectors.toList() allows the null elements.

Collectors.toList() doesn't throw an Exception when a Stream containing null elements is collected:

Assertions.assertDoesNotThrow(() -> {
    Stream.of(null,null).collect(Collectors.toList());
});

Collectors.toUnmodifiableList() throws a NulPointerException when we collect a Stream containing null elements:

Assertions.assertThrows(NullPointerException.class, () -> {
    Stream.of(null,null).collect(Collectors.toUnmodifiableList());
});

Similarly, Stream.toList() also throws a NulPointerException when we try to collect a Stream containing null elements:

Assertions.assertDoesNotThrow(() -> {
    Stream.of(null,null).toList();
});

Therefore, this is something to watch out for when migrating our code from Java 8 to Java 10 or Java 16. We can't blindly use Stream.toList() in place of Collectors.toList() or Collectors.toUnmodifiableList().

3.4. Summary of Analysis

The following table summarizes the differences and similarities of the lists from our analysis:

4. When to Use Different toList() Methods

The main objective of adding Stream.toList() is to reduce the verboseness of the Collector API.

As shown previously, using the Collectors methods for getting Lists is very verbose. On the other hand, using the Stream.toList() method makes code neat and concise.

Nevertheless, as seen in earlier sections, Stream.toList() can't be used as a shortcut to Collectors.toList() or Collectors.toUnmodifiableList().

Secondly, the Stream.toList() uses less memory because its implementation is independent of the Collector interface. It accumulates the Stream elements directly into the List. So, in case we know the size of the stream in advance, it will be optimum to use Stream.toList().

Thirdly, we know that the Stream API provides the implementation only for the toList() method. It doesn't contain similar methods for getting a map or a set. So, in case we want a uniform approach to get any converters like list, map, or set, we'll continue to use the Collector API. This will also maintain consistency and avoid confusion.

Lastly, if we're using versions lower than Java 16, we have to continue to use Collectors methods.

The following table summarizes the optimum usage of the given methods:

5. Conclusion

In this article, we analyzed the three most popular ways of getting a List from a Stream. Then, we looked at the main differences and similarities. And, we also discussed how and when to use these methods.

As always, the source code for the examples used in this article is available over on GitHub.