Java 8 Collectors API Tutorial With Real Time Examples

A quick practical guide to Java 8’s Collectors api. Example programs on various useful reduction operations and accumulating elements into collections

1. Overview

In this tutorial, We’ll be learning to Java 8 Collectors API in-depth with all methods and example programs. Collectors is a public final class that extends Object class.

Read this article completely with patience. You will definitely become a master in Java 8’s Collectors by end of this post.

Collectors class provides various useful reduction operations, such as accumulating elements into collections, summarizing elements according to various criteria, etc

This has many methods that are very useful when working with Stream api.

Few methods: toList(), toMap(), toCollection(), joining(), summingInt(), groupingBy() and partitioningBy(), etc.

We will see the example programs on the below Collectors methods and how to use them.

Collectors API Methods:

1. collect()
2. toList()
3. toSet()
4. toUnmodifiableSet()
5. toUnmodifiableList(()
6. toCollection()
7. toMap()
8. toUnmodifiableMap()
9. summingInt()
10. averagingInt() / averagingLong() / averagingDouble()s
11. counting()
12. joining()
13. groupingBy()
14. partitioningBy()
15. toConcurrentMap()
16. filtering()
17. flatMapping()
18. maxBy()
19. minBy()
20. reducing()
21. summarizingDouble() / summarizingInt() / summarizingLong()
22. teeing()

Note: All methods in the Collectors class are static. So it is good to use static import.

If you are using many methods then use static import.

If you are using only a few then use like this.

We will be using the below Employee class in this article.

Creating an Employee List.

2. Java 8 Stream.collect() Example

Java 8’s most powerful stream method is collect() method. Which is also called a Terminal method. This is part of Stream API.

It allows us to perform mutable fold operations (repackaging elements to some data structures and applying some additional logic, concatenating them, etc.) on data elements held in a Stream instance.

The strategy for this operation is provided via Collector interface implementation.

3. Collectors.toList() Example

toList() collector can be used for collecting all Stream elements into a List instance. 

Example to collect all employee names into List using toList() method.

Output:

But, there are no guarantees on the type, mutability, serializability, or thread-safety of the List returned.

If you need more control over what type of List should be returned then should use toCollection(Supplier) method.

4. Collectors.toSet() Example

toSet() collector is used for collecting all Stream elements into a Set instance. 

Example to collect all the regions into Set.

Output:

But, there are no guarantees on the type, mutability, serializability, or thread-safety of the Set returned.

If you need more control over what type of Set should be returned then should use the toCollection(Supplier) method.

5. Collectors.toUnmodifiableSet() Example

This collects the elements into an unmodifiable set.

The set is created using the toSet() method can be modified. 

Output:

toUnmodifiableSet() method works similar to the toSet() but this set can not be modified.

Output:

If we try to modify set then will throw UnsupportedOperationException.

Exception:

The returned collector does not allow null values. This will throw NullPointerException if it is presented with a null value.

The above code will cause NullPointerException. The same will be in the case of the toSet() method.

6. Collectors.toUnmodifiableList(() Example

This is similar to the toList() but toUnmodifiableList will collect elements into an unmodifiable List.

Output:

This list holds duplicates, unlike Set.

If List has null value then it will throw java.lang.NullPointerException like toUnmodifiableSet.

7. Collectors.toCollection() Example

As you probably already noticed, when using toSet() and toList() collectors, you can’t make any assumptions of their implementations. 

If you want to use a custom implementation or LinkedList or TreeSet, you will need to use the toCollection collector with a provided collection of your choice.

Example to collect the names into LinkedList as opposed to default List implementation.

Output:

Another example to collect regions into TreeSet.

Output:

See the output is sorted because TreeSet sorts the values in it.

Note: This method does not work with immutable objects. In such type of cases, We must write custom Collector implementation or Use collectingAndThen().

8. Collectors.toMap() Example

toMap() Syntax:

Using toMap() method, A stream can be converted into a Map. But, this method needs two parameters.

keyMapper

valueMapper

These two are implementations of Function Functional Interface.

Functional Interface Function has a functional method R apply(T t) that accepts one argument and produces a result.

keyMapper will be used for extracting a Map key from a Stream element, and valueMapper will be used for extracting a value associated with a given key.

Now, We will create a map from a stream such that the map key is emp id and value is corresponding employee object.

e refers to the Employee object and getting its id by calling getId() method.

This method returns a function that always returns its input argument.

Function.identity() method does take one object as an argument and returns the same object with no change.

Output:

What happens if employeeList has duplicate employees with the same employee id.

Now adding a duplicate emp object with the same emp id but the different name “Larry Page”.

Added a new emp object with emp id = 400.

Will throw the Runtime Exception as follow.

Note: Map does not check the duplicate objects but does not allow duplicate keys.

toMap() function takes 3rd argument as BinaryOperator Functional Interface which has a functional method R apply(T t, U u). This functional method takes two arguments. In our case, the first argument takes the original employee, Second argument takes the duplicate employee and returns the employee object.

Output:

Here BinaryOperator will be invoked when there the same key appears. And returning duplicate objects from BinaryOperator apply() method. That replaces the old employee with a new duplicate employee. See the below output.

Observe the employee with id 400 has a new name “Larry Page”. If we want to keep existing emp in the map and ignore the duplicate emp then we should return emp instead of sameEmp.

9. Collectors.toUnmodifiableMap() Example

Syntax:

Returns a Collector that accumulates the input elements into an unmodifiable Map, whose keys and values are the result of applying the provided mapping functions to the input elements. 

This function will throw NullPointerException if the keyMapper, valueMapper, or mergeFunction is null.

10. Collectors.summingInt() Example

summingInt() Method does the summation of all extracted elements from the stream and returns Integer.

Syntax:

Example:

Finding the sum of all emp id’s using summingInt() method.

Output:

This method is to sum of int values. 

Similar to this, Collector api has methods for summingLong(), summingDouble().

Now, let us see the code to get the sum of salaries of all employees.

Output:

Collectors.summingDouble : 1400000.0

11. Collectors.averagingInt() / averagingLong() / averagingDouble() Examples

Collectors api has methods to get the average for integer, Long and Double values. These methods become now very handy to perform avg operations.

Internally arithmetic logic is applied for stream elements.

Syntax:

Here all these versions of methods return Double rather that its names describe.

Examples:

Output:

12. Collectors.counting() Example

Syntax:

This method returns a Long value and just counts the values present in the Stream.

Output:

13. Collectors.joining() Example

Syntax:

Joining() method does append the all contents of Stream the order they appear.

This is mainly designed for Strings with Stream<String>.

All versions of joining() methods return String.

joining() Example:

Output:

This joining() method just concatenates without adding any delimiter.

joining(CharSequence delimiter) Example:

If we want to add some delimiter then we should use this variant of the method.

Output:

Now observe the output that added * delimiter for each name.

joining(CharSequence delimiter, CharSequence prefix, CharSequence suffix) Example:

Example code to add some value to before and after delimiter is applied.

prefix will be added at the beginning after concatenating the delimiter to all values.

suffix will be added at the end after concatenating the delimiter to all values.

Output:

14. Collectors.groupingBy() Example

This groupingBy function works similar to the Oracle GROUP BY clause.

GroupingBy collector is used for grouping objects by some property and storing results in a Map instance.

We will see the example of the group by an employee region.

Output:

The below two employees are stored under the “North America” region. 

By default, Map values are stored in the List.

If we want to make value is set then we should specify to the groupingBy() method as below.

15. Collectors.partitioningBy() Example

Syntax:

First, Take a look at the syntax.

From syntax, This method returns a Map and Boolean is key, List<T> as value. The returned Map always contains mappings for both false and true keys only.

partitioningBy() method takes Predicate Functional Interface which returns Boolean. Because of this, Key is always determined as Boolean and value is Employee object.

Output:

Returned Map value is always a List. If you want to change it to another collection then we must use the below variant of groupingBy() method.

public static <T,D,A> Collector<T,?,Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate, Collector< super T,A,D> downstream)

Examples:

To make working for TreeSort, the Employee class must implement
Comparable interface. Otherwise, will throw ClassCastException.

Note: If a partition has no elements, its value in the resulting Map will be an empty List.

16. Collectors.toConcurrentMap() Example

We have seen already toMap() in this post. If we want to store the result in Concurrent Map then we should use the toConcurrentMap() method.

Syntax:

Examples:

17. Collectors.filtering() Example

Stream api already has a filter() function. But, this is a very convenient way to do at a single place doing condition and collecting into List or Set.

Based on developer choice, We can choose Collectors or Stream api. Mostly, All use stream api filter() method.

Syntax:

Examples:

For all stream elements, the first Predicate will be executed first and next downstream will be applied.

Output:

18. Collectors.flatMapping() Example

This is very useful to convert a Collection of Collections into a flat map. The
flatMapping() collectors are most useful when used in a multi-level reduction, such as downstream of a groupingBy or partitioningBy. 

Syntax:

Example:

Creating LineItem class.

Creating Customer class which has HAS-A relationship to LineIteam with List.

Creating Customer object 1

Creating Customer object 2

Creating Customer object 3

Creating Customer object 4

Using flatMapping() method to find the LineItems by gender.

Output:

Finding the count LineItemas count by gender.

Now instead of calling collecting the output of flatMapping() into Set, invoke Collectors.counting() that count the number of Line items by Gender.

Output:

19. Collectors.maxBy() Example

maxBy() method finds the max element from the stream. To find the max element, we must pass the Comparator implementation to this method as argument.

This method does as same as reducing(BinaryOperator.maxBy(comparator)).

Syntax:

This method returns the Optional object. This object avoids NullPointerException by using isPresent() method of Optional class.

Example:

Collectors.maxBy() Example to find highest emp id object.

Output:

20. Collectors.minBy() Example

minBy() is opposite to the maxBy() method. minBy() method is used to find a minimum element from the Stream. We should pass the
Comparator as an argument.

This method does as same as reducing(BinaryOperator.minBy(comparator)).

Syntax:

This method also returns an Optional instance similar to the maxBy() method.

Example:

Collectors.minBy() Example to find min emp id object.

Output:

21. Collectors.reducing() Example

Returns a Collector which performs a reduction of its input elements under a specified BinaryOperator. The result is described as an Optional<T>.

Syntax:

Example:

Output:

Min Emp using reducing() method : Employee [id=100, name=Sundar, age=47, region=North America, sal=450000.0]

We can find the max emp element using maxBy static method of BinaryOperator.

22. Collectors.summarizingDouble() / summarizingInt() / summarizingLong() Example

summarizingDouble() method does statistics operations on double values in the stream.

This method returns DoubleSummaryStatistics which holds count, min, max, sum, and the average for all double values in the stream. This helps like a utility method.

Syntax:

Example:

Output:

In the same way for Integer and Long values separate methods provided to get the statistics using summarizingInt() and summarizingLong().

23. Collectors.teeing() Example

teeing() method is used to combine two Collectors output using a special merger function. This method is added in Java 12.

Syntax:

The above syntax is difficult to understand and simplified as below.

Simple words, This method accepts two collectors and one merger function. Merger function takes outputs of two collectors and performs operations. Finally, returns some value or object or maybe collection.

Example:

Collectors teeing() example to find the average of first 100 numbers.

Collector 1: Finds the sum of 100 numbers from the stream.

Collector 2: Finds count of numbers in the stream.

Merger: Takes sum and count as input and does the average operation.

Output:

24. Complete Collectors Methods Examples

All Collectors utility class all methods with examples in a single program.

Output:

25. Conclusion

In this tutorial, We have covered in-depth on Collectors API.

First, Covered the introduction to the Collectors api and what it does.

Next, Shown the example programs on each and every method of Collectors.

All methods are declared as Static in Collectors class. So, Directly methods can be accessed with class name E.g. Collectors.toList(), Collectors.groupingBy() etc.

Commonly used method of Collectors are toList(), toMap(), toCollection(), joining(), summingInt(), groupingBy() and partitioningBy().

All the examples shown are available over GitHub.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.