Flattening Nested Collections with flatMap

1. The Challenge of Nested Collections

Let's start with a practical problem. Imagine you have a list of employees, and each employee has worked in multiple cities. Your task is to compile a single, consolidated list of all unique cities where your employees have experience.

Using what we learned in the last lesson, you might try using map:

class Employee {
    // ... constructor, getters
    private String name;
    private List<String> citiesWorkedIn;
}

List<Employee> employees = // ... list of employees

// Let's try to get all cities using map()
List<List<String>> citiesByEmployee = employees.stream()
                                               .map(Employee::getCitiesWorkedIn)
                                               .collect(Collectors.toList());

System.out.println(citiesByEmployee); 
// Output might be: [[Pune, Mumbai], [Pune, Bangalore], [Noida, Gurgaon]]

As you can see, map does its job perfectly: it transforms each Employee object into a List<String>. The result is a List<List<String>>, a list of lists. This is a nested collection and not the flat List<String> of unique cities we wanted.

This is precisely the problem flatMap is designed to solve.

2. Understanding flatMap: The Flattening Transformer

flatMap is best understood as a two-step operation:

1. Map: It applies a function to each element, just like map. However, this function must return a Stream of new elements.
2. Flat: It then takes all of these generated streams and "flattens" them into a single, combined stream.

Let's look at their signatures to understand the key difference:

• map(Function<T, R>): The provided function transforms an element of type T into a single element of type R.
• flatMap(Function<T, Stream<R>>): The provided function transforms an element of type T into a stream of elements of type R.

The core idea is that flatMap allows one element in the input stream to be mapped to zero, one, or many elements in the output stream, which are then all seamlessly combined.

3. flatMap in Action: Solving the Nested Collection Problem

Now, let's solve our initial problem of getting a flat list of cities using flatMap.

List<String> allCities = employees.stream()
    .flatMap(employee -> employee.getCitiesWorkedIn().stream()) // 1
    .distinct() // 2
    .collect(Collectors.toList()); // 3

System.out.println(allCities);
// Output will be: [Pune, Mumbai, Bangalore, Noida, Gurgaon]

Let's break down the pipeline:

1. .flatMap(employee -> employee.getCitiesWorkedIn().stream()): For each Employee, we get their List<String> of cities and then call .stream() on it. This turns the List<String> into a Stream<String>. flatMap then merges all these small streams into one large Stream<String>.
2. .distinct(): This is an intermediate operation that removes duplicate elements from the stream.
3. .collect(Collectors.toList()): The terminal operation gathers the unique city names into our final List<String>.

A Common Interview Scenario: Customer and PhoneNumbers

Another classic example you'll find in interviews involves a Customer class with a list of phone numbers.

The pattern is always the same: when you have a Stream<A> and A contains a Collection<B>, you use flatMap to get a Stream<B>.

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

public class WordExtractor {
    public static void main(String[] args) {
        List<String> sentences = List.of("the quick brown fox", "jumps over the lazy dog");

        List<String> words = sentences.stream()
                .flatMap(sentence -> Arrays.stream(sentence.split(" ")))
                .collect(Collectors.toList());

        System.out.println(words);
        // Output: [the, quick, brown, fox, jumps, over, the, lazy, dog]
    }
}

4. Interview Problem Workshop: Combining Operations

In interviews, you'll often be asked to solve problems that require combining flatMap with other operations like map or filter.

Problem: Given a list of lists of integers, return a single list containing the square of each number.

Input: List.of(List.of(1, 2), List.of(3, 4, 5), List.of(6))
Expected Output: [1, 4, 9, 16, 25, 36]

How would you build the pipeline?

1. First, you need to flatten the List<List<Integer>> into a single stream of integers. This is a job for flatMap.
2. Then, you need to transform each integer in the flattened stream into its square. This is a one-to-one transformation, so it's a job for map.

The solution demonstrates a powerful and common pattern:

List<List<Integer>> listOfLists = List.of(List.of(1, 2), List.of(3, 4, 5), List.of(6));

List<Integer> squaredNumbers = listOfLists.stream()
    .flatMap(List::stream) // Flattens List<List<Integer>> to Stream<Integer>
    .map(n -> n * n)       // Squares each number
    .collect(Collectors.toList());

System.out.println(squaredNumbers);

By using flatMap and map together, you can perform complex transformations on nested data structures with clean, declarative code.

Conclusion

You've now added another critical tool to your Java Streams toolkit. While map is your go-to for one-to-one transformations, flatMap is essential for handling one-to-many scenarios and flattening nested data structures.

Key Takeaways for Your Interview:

• Recognize the Pattern: If an interview problem involves a structure like List<List<T>> or a List<User> where each user has a List<Purchase>, and the goal is to process all T's or Purchase's in a single collection, flatMap is almost certainly part of the solution.
• Map vs. FlatMap: Be ready to articulate the difference clearly. map's function returns a single value (T -> R). flatMap's function must return a Stream (T -> Stream<R>). flatMap effectively maps and then flattens.
• Build Complex Pipelines: Show your proficiency by combining flatMap with map, filter, and distinct to solve multi-step problems. The order matters: flatten first, then transform or filter the individual elements.

Preview of the Next Lesson:
We've learned how to transform and flatten streams. The next logical step is to organize the elements of a stream into more complex data structures. In our next lesson, we will explore how to group and partition collection data effectively using built-in collectors like groupingBy and partitioningBy, allowing you to create Maps from your streams.