Java Stream flatMap() Method

The flatMap() method in Java, part of the java.util.stream.Stream interface, is used to transform each element of the stream into a new stream and then flatten these streams into a single stream. This method is useful for handling nested structures or when you need to produce a dynamic number of results for each input element.

Table of Contents

1. Introduction
2. flatMap() Method Syntax
3. Understanding flatMap()
4. Examples
   • Basic Usage
   • Using flatMap() with Nested Structures
5. Real-World Use Case
6. Conclusion

Introduction

The flatMap() method returns a stream consisting of the results of replacing each element of the original stream with the contents of a mapped stream produced by applying a provided mapping function. This method is an intermediate operation, meaning it returns a new stream and does not modify the original stream.

flatMap() Method Syntax

The syntax for the flatMap() method is as follows:

<R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper)

Parameters:

• mapper: A function to apply to each element, which produces a stream of new values.

Returns:

• A new Stream consisting of the flattened results of the mapped streams.

Throws:

• This method does not throw any exceptions.

Understanding flatMap()

The flatMap() method allows you to take each element of the original stream, transform it into a new stream, and then combine these multiple streams into a single stream. This is useful for processing nested collections or generating multiple results for each input element.

Examples

Basic Usage

To demonstrate the basic usage of flatMap(), we will create a Stream of lists and use flatMap() to flatten these lists into a single stream of elements.

Example

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class FlatMapExample {
    public static void main(String[] args) {
        List<Integer> list1 = Arrays.asList(1, 2, 3);
        List<Integer> list2 = Arrays.asList(4, 5, 6);
        List<Integer> list3 = Arrays.asList(7, 8, 9);

        Stream<List<Integer>> stream = Stream.of(list1, list2, list3);

        // Use flatMap() to flatten the lists into a single stream of elements
        Stream<Integer> flatMappedStream = stream.flatMap(List::stream);

        // Print the flattened elements
        flatMappedStream.forEach(System.out::println);
    }
}

Output:

1
2
3
4
5
6
7
8
9

Using flatMap() with Nested Structures

This example shows how to use flatMap() to process nested structures, such as a list of sentences, where each sentence is a list of words.

Example

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

public class FlatMapNestedExample {
    public static void main(String[] args) {
        List<String> sentence1 = Arrays.asList("Hello", "world");
        List<String> sentence2 = Arrays.asList("How", "are", "you");
        List<String> sentence3 = Arrays.asList("I", "am", "fine");

        Stream<List<String>> sentences = Stream.of(sentence1, sentence2, sentence3);

        // Use flatMap() to flatten the sentences into a single stream of words
        Stream<String> flatMappedStream = sentences.flatMap(List::stream);

        // Print the flattened words
        flatMappedStream.forEach(System.out::println);
    }
}

Output:

Hello
world
How
are
you
I
am
fine

Real-World Use Case

Flattening a List of Lists of Employees

In real-world applications, the flatMap() method can be used to flatten a list of lists of employees into a single stream of employees.

Example

import java.util.Arrays;
import java.util.List;
import java.util.stream.Stream;

public class FlatMapEmployeeExample {
    static class Employee {
        String name;

        Employee(String name) {
            this.name = name;
        }

        @Override
        public String toString() {
            return name;
        }
    }

    public static void main(String[] args) {
        List<Employee> department1 = Arrays.asList(new Employee("Alice"), new Employee("Bob"));
        List<Employee> department2 = Arrays.asList(new Employee("Charlie"), new Employee("David"));
        List<Employee> department3 = Arrays.asList(new Employee("Eve"), new Employee("Frank"));

        Stream<List<Employee>> departments = Stream.of(department1, department2, department3);

        // Use flatMap() to flatten the departments into a single stream of employees
        Stream<Employee> flatMappedStream = departments.flatMap(List::stream);

        // Print the employees
        flatMappedStream.forEach(System.out::println);
    }
}

Output:

Alice
Bob
Charlie
David
Eve
Frank

Conclusion

The Stream.flatMap() method is used to transform each element of the stream into a new stream and then flatten these streams into a single stream. This method is particularly useful for handling nested structures or generating multiple results for each input element. By understanding and using this method, you can efficiently manage and process streams of values in your Java applications, transforming and flattening complex data structures as needed.