Why Stream.toList() Throws UnsupportedOperationException vs collect(Collectors.toList())

Background

In a development environment an UnsupportedOperationException appeared when a colleague used

stringList.stream().filter(number -> Long.parseLong(number) > 1).toList()

and then tried to add elements to the returned list, revealing misuse of an unmodifiable collection.

Difference between Stream.toList() and collect(Collectors.toList())

JDK version: 21

IDE: IDEA

Since Java 16 the Stream API provides a direct toList() terminal operation. The list returned by toList() is unmodifiable; any mutating call (e.g., add, remove) throws UnsupportedOperationException. The classic collect(Collectors.toList()) creates a mutable ArrayList.

/**
 * Accumulates the elements of this stream into a {@code List}. The elements
 * are in encounter order, if one exists. The returned List is unmodifiable;
 * calls to any mutator method will always cause {@code UnsupportedOperationException}.
 * @since 16
 */
@SuppressWarnings("unchecked")
default List<T> toList() {
    return (List<T>) Collections.unmodifiableList(new ArrayList<>(Arrays.asList(this.toArray())));
}

The implementation of toList() ultimately delegates to Collections.unmodifiableList, which wraps the supplied list in an unmodifiable view:

return (list instanceof RandomAccess)
        ? new UnmodifiableRandomAccessList<>(list)
        : new UnmodifiableList<>(list);

Although the list itself cannot be altered, the objects contained in it can still be mutated if they are mutable.

List<String> stringList = List.of("1", "2", "3");
List<String> largeNumberList = stringList.stream()
    .filter(number -> Long.parseLong(number) > 1)
    .toList(); // unmodifiable
List<String> largeNumberList2 = stringList.stream()
    .filter(number -> Long.parseLong(number) > 1)
    .collect(Collectors.toList()); // mutable

largeNumberList.add("4"); // throws UnsupportedOperationException
largeNumberList2.add("4"); // succeeds

User userZhang = new User("ZhangSan");
User userLi = new User("LiSi");
List<User> userList = List.of(userZhang, userLi);
List<User> filterList = userList.stream()
    .filter(user -> "LiSi".equals(user.name))
    .toList(); // unmodifiable list of mutable objects
User first = filterList.getFirst(); // Java 21
first.name = "WangWu"; // mutates the underlying object
filterList.forEach(u -> System.out.println(u.name));

How to use (ignoring performance)

Use Stream.toList() when you need an immutable list. If you prefer a mutable list and want to silence static‑analysis warnings, replace collect(Collectors.toList()) with collect(Collectors.toCollection(ArrayList::new)).

Source: juejin.cn/post/7325717778597904420