flatMap()

#Introduction

This topic confuses almost every Java developer at first. A common pattern in interviews: candidates know map(), but don't really understand flatMap().

Once you understand flatMap(), you'll solve problems involving nested lists, Orders → Items, Employee → Skills, Customer → Orders, Department → Employees, Files → Lines, JSON arrays and database relationships. A must-know topic for Spring Boot developers.

By the end of this chapter you'll master what flatMap() actually does, the difference between map() and flatMap(), flattening nested collections, flatMapToInt(), and advanced interview problems.

#First, Understand map()

List<String> names = Arrays.asList("John", "Alex", "David");

names.stream()
     .map(String::toUpperCase)

JOHN
ALEX
DAVID

One input → one output. Every element becomes exactly one element.

Now Imagine This

Instead of John, suppose every employee has skills: John → Java, SQL, Spring.

Now one employee becomes multiple values. map() cannot flatten this — this is where flatMap() comes in.

#What is flatMap()?

#The Classic Example

List<List<Integer>> list = Arrays.asList(
        Arrays.asList(1, 2),
        Arrays.asList(3, 4),
        Arrays.asList(5, 6)
);

[
  [1, 2],
  [3, 4],
  [5, 6]
]

Using map()

list.stream()
    .map(List::stream)

Result: Stream<Stream<Integer>> — a stream of streams of numbers. Not useful.

Using flatMap()

list.stream()
    .flatMap(List::stream)
    .forEach(System.out::println);

1
2
3
4
5
6

Why "Flat"?

#Employee Skills Example

class Employee {
    String name;
    List<String> skills;
}

Data: John → Java, Spring, SQL and Alex → Docker, AWS. Requirement: get all skills.

employees.stream()
         .flatMap(e -> e.getSkills().stream())
         .forEach(System.out::println);

Java
Spring
SQL
Docker
AWS

Remove Duplicate Skills

employees.stream()
         .flatMap(e -> e.getSkills().stream())
         .distinct()
         .forEach(System.out::println);

No duplicates — if two employees both know Java, it's printed once.

Count Skills

long count = employees.stream()
        .flatMap(e -> e.getSkills().stream())
        .count();

Sort Skills

employees.stream()
         .flatMap(e -> e.getSkills().stream())
         .sorted()
         .forEach(System.out::println);

flatMap + filter

Need only Java-related skills:

employees.stream()
         .flatMap(e -> e.getSkills().stream())
         .filter(skill -> skill.startsWith("Java"))
         .forEach(System.out::println);

#Orders Example

class Order {
    List<Item> items;
}

Need all items:

orders.stream()
      .flatMap(order -> order.getItems().stream())
      .collect(Collectors.toList());

A very common Spring Boot pattern.

#Customer → Orders → Items

Need all items:

customers.stream()
         .flatMap(customer -> customer.getOrders().stream())
         .flatMap(order -> order.getItems().stream())
         .collect(Collectors.toList());

Notice the multiple flatMap() calls.

#File Processing

try (Stream<String> lines = Files.lines(path)) {
    lines.flatMap(line -> Arrays.stream(line.split(" ")))
         .forEach(System.out::println);
}

Output: every word in the file. Very useful.

#flatMapToInt()

class Student {
    List<Integer> marks;
}

Need total marks:

int total = students.stream()
        .flatMapToInt(s -> s.getMarks().stream().mapToInt(Integer::intValue))
        .sum();

#map() vs flatMap()

Asked constantly.

#Real Spring Boot Examples

// Employee -> skills
employees.stream()
         .flatMap(e -> e.getSkills().stream());

// Orders -> items
orders.stream()
      .flatMap(o -> o.getItems().stream());

// Department -> employees
departments.stream()
           .flatMap(d -> d.getEmployees().stream());

// Roles -> permissions
roles.stream()
     .flatMap(r -> r.getPermissions().stream());

JWT Roles

Suppose a JWT contains ROLE_ADMIN, ROLE_USER and ROLE_MANAGER, and each role maps to a set of permissions:

claims.getRoles()
      .stream()
      .flatMap(role -> role.getPermissions().stream())

Very common in Spring Security.

#Practice Problems

class Employee {
    String name;
    List<String> skills;
}

1. Print all skills.
2. Print unique skills.
3. Sort all skills.
4. Count skills.
5. Print only skills starting with "J".
6. Convert skills into a Set.
7. Join all skills with commas.
8. Find the longest skill name.
9. Count unique skills.
10. Find the alphabetically first skill.

class Customer {
    List<Order> orders;
}

class Order {
    List<Item> items;
}

1. Get all orders.
2. Get all items.
3. Count all items.
4. Find unique items.
5. Find the most expensive item.
6. Find the cheapest item.
7. Group items by category.
8. Count items by category.
9. Sort items by price.
10. Find the top 5 expensive items.

Senior Interview Challenge (5+ Years)

class Company {
    List<Department> departments;
}

class Department {
    String name;
    List<Employee> employees;
}

class Employee {
    String name;
    List<String> skills;
}

Return a Map<String, Set<String>> where key = department name and value = unique, sorted employee skills.

Map<String, Set<String>> result = company.getDepartments().stream()
        .collect(Collectors.toMap(
                Department::getName,
                department -> department.getEmployees().stream()
                        .flatMap(employee -> employee.getSkills().stream())
                        .collect(Collectors.toCollection(TreeSet::new))
        ));

Why this is a great interview solution:

• toMap() creates the department-to-skills mapping.
• flatMap() flattens all employee skill lists into one stream.
• TreeSet both removes duplicates and keeps the skills sorted.

#Senior Java Tips

1. The Golden Rule

Ask yourself: does each input produce exactly one output?

2. Don't confuse flatMap() with Collectors.flatMapping()

Collectors.groupingBy(
        Employee::getDepartment,
        Collectors.flatMapping(e -> e.getSkills().stream(), Collectors.toSet())
)

3. Watch for null

This can throw a NullPointerException:

.flatMap(e -> e.getSkills().stream())

If getSkills() might return null, use:

.flatMap(e -> Optional.ofNullable(e.getSkills())
        .orElse(Collections.emptyList())
        .stream())

This makes your pipeline null-safe.

#You've Completed the Core of Java Streams

You now understand the stream lifecycle, filter(), map(), sorted(), distinct(), limit(), skip(), reduce(), collect(), groupingBy(), partitioningBy(), advanced collectors and flatMap() — the APIs you'll use in the majority of enterprise Java codebases. From here on, the focus shifts from learning APIs to solving problems.