When accessing 3rd party APIs with pagination, we tend to see the same pattern over and over again. Usually, a response [represented as POJO] looks something like this:
[java]
classResult {
public List getItems[] {
}
}
[/java]
Be it from a third party service or your own APIs, after retrieving all results of the API call, we end up with something like a List. Great. We dont really care about the response itself, were actually interested in all the items of the responses. Lets say we want all the items, filter some of them out and transform them into a TransformedItem. People usually start writing something like the following:
[java]
List results =
List newItems = results.stream[]
.map[result -> result.getItems[]]
.filter[item -> item.isValid[]]
.map[TransformedItem::new]
.collect[toList[]];
[/java]
Ooops, this doesnt even compile. The problem is that the first map doesnt return a Stream but actually a Stream. In order to actually merge/flatten all those nested lists, you can use Stream#flatMap. The difference is quite simple. #map allows you to transform an element in the stream into another element. On the other hand, #flatMap allows you to convert a single element to many [or no] elements.
[java]
List results =
List newItems = results.stream[]
.map[result -> result.getItems[]]
.flatMap[List::stream]
.map[TransformedItem::new]
.collect[toList[]];
[/java]
Just in case youre working with a 3rd party API that returns something ugly as List, you can use the same pattern, just choose the corresponding the flatMap function.
[java]
classQueryResponse {
public Item[] getItems[] {
}
}
List newItems = results.stream[]
.map[result -> result.getItems[]]
.flatMap[Arrays::stream]
.map[TransformedItem::new]
.collect[toList[]];
[/java]
Have fun with #flatMap and let me know in the comments about how you used #flatMap in your scenarios. A great explanation of how to compose streams and some concepts behind streams can be found in Martin Fowler Collection Pipeline.