Using Java Stream collect() to Build Collections
Learn how Java's Stream.collect() works and which Collectors to use for lists, maps, grouping, partitioning, joining, and custom collectors, plus common pitfalls to avoid.

When you call collect() on a Stream, you are performing a mutable reduction: the stream's elements are accumulated into a mutable container, such as a List, Set, or Map. The collect() operation is the standard way to turn a stream back into a concrete collection, and it gives you more control than simple iteration because you can specify exactly how elements are combined, grouped, or transformed.
The collect() method takes a Collector<T, A, R> that defines four functions: how to create a new result container, how to add an element to that container, how to merge two containers when the stream is processed in parallel, and how to transform the container into the final result. The Collectors utility class provides ready-made collectors for the most common cases, but you can also build your own when the built-in ones do not fit.
The Role of collect() in the Stream Pipeline
A stream pipeline typically starts with a source, applies intermediate operations like filter() and map(), and ends with a terminal operation. collect() is one such terminal operation and is designed for accumulating elements into a mutable result collection. Other terminal operations like forEach() or reduce() either produce side effects or a single combined value; with collect(), you can produce a List, Set, Map, or any custom collection type.
The signature is:
<R, A> R collect(Collector<? super T, A, R> collector)There is also a three-argument overload that lets you supply the supplier, accumulator, and combiner directly, but in practice you almost always use the Collectors factory methods because they handle the details correctly.
Choosing the Right Collector
The Collectors class provides a set of static methods that cover the majority of real-world needs. The most common are:
| Collector | Result | Typical Use |
|---|---|---|
toList() | List<T> | Preserve encounter order for ordered streams; allow duplicates |
toSet() | Set<T> | Remove duplicate elements according to equals(); no order guarantee |
toMap() | Map<K,V> | Map keys to values; duplicate keys require a merge function |
groupingBy() | Map<K, List<V>> | Group elements by a classifier function |
partitioningBy() | Map<Boolean, List<V>> | Split elements into two groups by a predicate |
joining() | String | Concatenate CharSequence elements |
Each collector has specific behavior regarding order, nulls, and parallelism. For example, toList() does not guarantee the exact implementation, but it does preserve encounter order for sequential streams. toSet() does not guarantee order, and it removes duplicate elements using equals(). toMap() requires you to handle duplicate keys, otherwise it throws an IllegalStateException.
Collecting into Lists, Sets, and Maps
The simplest use of collect() is to collect a stream into a list. For example:
List<String> names = Stream.of("Alice", "Bob", "Carol")
.filter(name -> name.length() > 3)
.collect(Collectors.toList());This typically creates an ArrayList and adds each filtered element to it. If you need a specific list implementation, you can pass a supplier to toCollection():
List<String> linkedList = Stream.of("a", "b", "c")
.collect(Collectors.toCollection(LinkedList::new));Collecting to a set is equally straightforward, but be aware that duplicate elements are silently removed:
Set<Integer> uniqueIds = Stream.of(1, 2, 2, 3)
.collect(Collectors.toSet());Collecting to a map is more interesting because you must provide both a key and a value function. If the key function returns duplicates, the collector throws an exception unless you supply a merge function:
Map<Integer, String> idToName = people.stream()
.collect(Collectors.toMap(
Person::getId,
Person::getName,
(existing, replacement) -> existing
));The merge function decides which value to keep when two elements share the same key. Without it, the collector fails at runtime, which is a common source of bugs.
Grouping Data with groupingBy
groupingBy() is one of the most powerful collectors. It classifies each element using a classifier function and collects elements with the same classification into a List by default. For example, to group a list of orders by customer ID:
Map<Long, List<Order>> ordersByCustomer = orders.stream()
.collect(Collectors.groupingBy(Order::getCustomerId));The result is a Map where each key is a distinct customer ID and the value is a list of that customer's orders. You can change the downstream collector to produce a different value type. For instance, to count orders per customer, use counting() as the downstream:
Map<Long, Long> orderCountByCustomer = orders.stream()
.collect(Collectors.groupingBy(Order::getCustomerId, Collectors.counting()));You can also supply a map factory to control the map implementation, which matters when you need a TreeMap for sorted keys or a LinkedHashMap for insertion order.
Partitioning Data with partitioningBy
partitioningBy() is a special case of groupingBy() where the classifier is a Predicate. It always returns a Map<Boolean, List<T>> with exactly two keys: true and false. This is useful when you need to split a stream into two groups based on a condition. For example:
Map<Boolean, List<Transaction>> partitioned = transactions.stream()
.collect(Collectors.partitioningBy(t -> t.getAmount() > 1000));Unlike groupingBy(), partitioningBy() is guaranteed to include both keys even if one group is empty. That makes it convenient for downstream processing where you expect both branches to exist.
Joining Strings with joining
When your stream contains strings or other CharSequence values, joining() is the cleanest way to concatenate them. The no-argument version simply concatenates all elements:
String concatenated = Stream.of("a", "b", "c")
.collect(Collectors.joining());More often you will want a delimiter, and optionally a prefix and suffix:
String csv = Stream.of("a", "b", "c")
.collect(Collectors.joining(", ", "[", "]"));
// Result: [a, b, c]The joining() collector only works with CharSequence elements. If your stream contains other types, you must map them to strings first.
Building a Custom Collector with Collector.of
When the built-in collectors do not meet your needs, you can create a custom collector using Collector.of(). You need to provide four functions: a supplier that creates the mutable result container, an accumulator that adds an element to the container, a combiner that merges two containers, and a finisher that transforms the container into the final result. You can also specify a set of Characteristics that describe the collector's behavior.
For example, to collect elements into an immutable list while preserving order, you could write:
Collector<String, List<String>, List<String>> immutableListCollector =
Collector.of(
ArrayList::new,
List::add,
(left, right) -> { left.addAll(right); return left; },
Collections::unmodifiableList
);This collector uses an ArrayList as the intermediate container, adds each element, merges two lists by adding all elements from the right into the left, and finally wraps the list in an unmodifiable view. It does not declare the CONCURRENT characteristic because an ArrayList is not thread-safe. Declaring concurrency characteristics on a collector whose container is not safe for concurrent access can corrupt results in a parallel stream. If you are not sure about the threading behavior, omit characteristics and let the stream merge partial containers normally.
Performance and Memory Considerations
collect() is a terminal operation that eagerly consumes the entire stream. That means all elements are held in memory in the resulting container. For large datasets, this can cause significant memory pressure. If you only need to process elements one at a time, consider using forEach() or an iterator instead of collecting everything into a list.
Parallel streams can speed up collection when the stream source is large and the accumulator is cheap, but the combiner must also be efficient. For a list collector, merging two partial lists requires copying the elements of one list into the other, and those copies can reduce the benefit of parallelism. Concurrent map collectors such as those backed by ConcurrentHashMap can avoid some of that copying by merging in place.
Another performance concern is the finisher. Collectors with finishers, such as toUnmodifiableList(), perform an extra transformation after accumulation. If you do not need immutability, the standard toList() avoids that extra transformation.
Common Mistakes and How to Avoid Them
A frequent error is using toMap() without a merge function when the key function is not unique. This throws IllegalStateException at runtime. Always consider whether duplicate keys are possible and provide a merge function that defines the desired behavior.
Another mistake is assuming that groupingBy() preserves encounter order. By default, it uses a HashMap, which does not guarantee order. If order matters, supply a TreeMap factory for sorted keys or use LinkedHashMap to preserve insertion order:
Map<String, List<Item>> grouped = items.stream()
.collect(Collectors.groupingBy(Item::getCategory, LinkedHashMap::new, Collectors.toList()));Finally, be careful when using collect() with parallel streams and custom collectors that are not thread-safe. The Characteristics set must accurately reflect the collector's concurrency behavior. If you mark a collector as CONCURRENT but its accumulator modifies a shared ArrayList without synchronization, the result will be corrupted. When in doubt, omit the CONCURRENT characteristic; the stream will then merge partial containers normally, which is correct albeit potentially slower.
Understanding how collect() works at the level of supplier, accumulator, combiner, and finisher gives you the ability to build exactly the collection you need, whether you are using a built-in collector or a custom one. The key is to choose the right collector for your data shape and to be explicit about ordering, duplicate handling, and concurrency behavior.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.