flatMap

Written Explanation

The problem: map keeps the boxes

Suppose each Order has a list of item names:

record Order(String customer, List<String> items) { }

If you write orders.stream().map(o -> o.items()), the lambda returns a List<String> for each order, so the result is a stream of lists: Stream<List<String>>. Collected, that is List<List<String>>, a list of lists. You wanted a single list of strings.

The solution: flatMap

flatMap takes a function that turns each element into a stream, then joins all those little streams into one stream:

List<String> allItems = orders.stream()
    .flatMap(o -> o.items().stream())
    .toList();

The function o -> o.items().stream() is called once per order, and returns that order's items as a stream. flatMap joins them. The result is Stream<String>, and toList() gives a plain List<String>.

The key rule is in the second column: the function you give to flatMap must return a stream. If you return a List, the code will not compile; add .stream(). If you want the method reference form for a list of lists, write flatMap(List::stream).

Because the function may return an empty stream, flatMap can also drop an element entirely: an order with no items contributes nothing. The Javadoc also notes that a null returned from the function is treated as an empty stream, but do not rely on returning null; return Stream.empty() or an empty collection's stream.

Flatten, then keep working

After flatMap, the rest of the pipeline works on single items, so every earlier tool applies:

orders.stream()
    .flatMap(o -> o.items().stream())
    .distinct()
    .sorted()
    .toList();

This produces every distinct item name ever ordered, in alphabetical order. Replace toList() with count() after a filter and you can answer "how many pens were ordered in total?".

Splitting text

A string can be turned into a stream of its words with Arrays.stream(text.split(" ")). Combined with flatMap, a list of lines becomes a stream of words:

lines.stream()
    .flatMap(line -> Arrays.stream(line.split("\\s+")))
    .filter(w -> !w.isEmpty())
    .map(String::toLowerCase)
    .distinct()
    .toList();

Notice the filter for empty strings. In Java, "".split(" ") returns an array with one empty string in it, so an empty line yields an empty "word". The example in this lesson shows it in the real output.

Keeping the parent: map inside flatMap

Sometimes flattening loses information you still need. After flattening orders to items, you no longer know which customer ordered each item. To keep it, build the pair inside the function with a nested map:

orders.stream()
    .flatMap(o -> o.items().stream().map(item -> o.customer() + ":" + item))
    .toList();

Read it from the inside out: for each order o, turn its items into labelled strings, then flatten all those streams into one. The lambda item -> ... can use o because it sits inside the outer lambda, where o is in scope.

map versus flatMap in one question

Ask: "For each input, do I get exactly one thing, or a collection of things?" One thing: map. A collection of things that should become part of the main stream: flatMap. Another test is the type: if you see Stream<List<...>> or List<List<...>> appear and you did not want it, you probably needed flatMap.

When a loop is clearer

A flatMap followed by a map that needs the parent's fields can get tangled. If you need several nested conditions, counters, or an early exit, a nested for loop with named variables may read better. Lesson 6 gives the test: could a teammate read it quickly?