flatMap() Method in Java 8

The Stream API was introduced in Java 8 that is used to process the collections of objects. It can be used by importing the java.util.stream package. In this section, we will discuss the Stream.flatMap() method of the Stream API. Also, we will discuss the key differences between the Stream.flatMap() and Stream.map() method in Java 8.

Before moving to the topic, first, we will understand the Stream.map() method. Because the flatMap() method is based on the map() method.

Java Stream.map() Method

The Stream.map() method performs an intermediate operation by using the mapper function. It produces a new stream for each element. It transforms all the streams into a single stream to provide the result. therefore, each element of the stream gets converted into a new stream.

Syntax:

R: It is a type parameter that represents the element type of the new stream.

mapper: It is a parameter that is non-interfering, stateless function to apply to each element.

Example of the map() Method

List citylist = Arrays.asList("delhi", "mumbai", "hyderabad", "ahmedabad", "indore", "patna"). stream(). map(String::toUpperCase).collect(Collectors.toList());

Consider the above statement for a map of the stream. It creates a resulting stream using the map(). In each iteration, map() creates a separate stream with the result by executing the mapper function. At last, map() transforms all streams into a single stream.

MapExample.java

import java.util.*;
public class MapExample 
{
public static void main(String args[])
{
System.out.println("Stream After applying the map() function: ");
//creats a list of integers
List<Integer> list = Arrays.asList(12, 45, 67, 19, 87, 2, 9);
//creating a new stream of the elements an prints the same using the foreach loop
list.stream().map(number -> number * 2).forEach(System.out::println);
}
}

Output:

Stream After applying the map() function: 
24
90
134
38
174
4
18

Java Stream.flatMap() Method

In Java 8 Streams, the flatMap() method applies operation as a mapper function and provides a stream of element values. It means that in each iteration of each element the map() method creates a separate new stream. By using the flattening mechanism, it merges all streams into a single resultant stream. In short, it is used to convert a Stream of Stream into a list of values.

Syntax:

The method takes a function as an argument. It accepts T as a parameter and returns a stream of R.

R: It is a type parameter that represents the element type of the new stream.

mapper: It is a parameter that is a non-interfering, stateless function to apply to each element. It produces a stream of new values.

In short, we can say that the flatMap() method helps in converting Stream<Stream<T>> to Stream<T>. It performs flattening (flat or flatten) and mapping (map), simultaneously. The Stream.flatMap() method combines both the operations i.e. flat and map.

Let's understand the meaning of flattening.

What is flattening?

Flattening is the process of converting several lists of lists and merge all those lists to create a single list containing all the elements from all the lists.

Flattening Example

Consider the following lists of lists:

Before Flattening: [[1, 2, 3, 4], [7, 8, 9, 0], [5, 6], [12, 18, 19, 20, 17], [22]]

After Flattening: [1, 2, 3, 4, 7, 8, 9, 0, 5, 6, 12, 18, 19, 20, 17, 22]

Example of the flatMap() Method

List country = Stream.of(Arrays.asList("Colombia", "Finland", "Greece", "Iceland", "Liberia", "Mali", "Mauritius"), Arrays.asList("Peru", "Serbia", "Singapore", "Turkey", "Uzbekistan", "Yemen", "Zimbabwe", "Greece", "Iceland")).flatMap(List::stream) .collect(Collectors.toList());

We can use a flatMap() method on a stream with the mapper function List::stream. On executing the stream terminal operation, each element of flatMap() provides a separate stream. In the final phase, the flatMap() method transforms all the streams into a new stream. In the above stream, we observe that it does not contain duplicate values.

Let's create a Java program and use the flatMap() method.

FlatMapExample.java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
public class FlatmapExample
{
public static void main(String args[]) 
{
//creating ArrayList    
List<String> productlist1 = Arrays.asList("Printer", "Mouse", "Keyboard", "Motherboard");
List<String>  productlist2 = Arrays.asList("Scanner", "Projector", "Light Pen");
List<String> productlist3 = Arrays.asList("Pen Drive", "Charger", "WIFI Adapter", "Cooling Fan");
List<String> productlist4 = Arrays.asList("CPU Cabinet", "WebCam", "USB Light", "Microphone", "Power cable");
List<List<String>> allproducts = new ArrayList<List<String>>(); 
//adding elements to the list
allproducts.add(productlist1);
allproducts.add(productlist2);
allproducts.add(productlist3);
allproducts.add(productlist4);
//creating a list of all products
List<String> listOfAllProducts = new ArrayList<String>();
//for each loop iterates over the list
for(List<String> pro : allproducts) 
{
for(String product : pro) 
{
//adds all products to the list    
listOfAllProducts.add(product);
}
}
System.out.println("List Before Applying mapping and Flattening: \n");
//prints stream before applying the flatMap() method
System.out.println(listOfAllProducts);
System.out.println();
//creats a stream of elemnts using flatMap()
List<String> flatMapList = allproducts .stream().flatMap(pList -> pList.stream()).collect(Collectors.toList()); 
System.out.println("List After Applying Mapping and Flattening Operation: \n"); 
//prints the new stream that we get after applying mapping and flattening 
System.out.println(flatMapList);        
}
}

Output:

List Before Applying mapping and Flattening: 
[Printer, Mouse, Keyboard, Motherboard, Scanner, Projector, Lighten, Pen Drive, Charger, WIFI Adapter, Cooling Fan, CPU Cabinet, WebCam, USB Light, Microphone]
List After Applying Mapping and Flattening Operation: 
[Printer, Mouse, Keyboard, Motherboard, Scanner, Projector, Light Pen, Pen Drive, Charger, WIFI Adapter, Cooling Fan, CPU Cabinet, WebCam, USB Light, Microphone]

Now, we have understood both the methods of the Stream class. Since we can easily point out the key differences between them.

Stream.flatMap() Vs. Stream.map()

The following table describes the key differences between Stream.flatMap() and Stream.map().

Stream.flatMap()	Stream.map()
It processes the stream of stream's values.	It processes the stream of values.
It performs mapping along with flattening.	It performs mapping only.
It transforms data from Stream> to Stream.	It transforms data from Stream to Stream.
It uses One-To-Many mapping.	It uses One-To-One mapping.
It's mapper function produces multiple values (stream of values) for each input value.	It's mapper function produces single values for each input value.
Use the flatMap() method when the mapper function is producing multiple values for each input value.	Use the map() method when the mapper function is producing single values for each input value.