Detailed explanation
In Java streams, map() transforms each input element into one output element, while flatMap() transforms each input element into a stream and then flattens those streams into one output stream. The distinction is the shape and number of results: map() preserves one result per input, whereas flatMap() can contribute zero, one, or many results per input. Use map() for direct transformations, such as converting names to uppercase, and flatMap() when each element contains or generates multiple values that should be processed together.
The generic signature of map() is <R> Stream<R> map(Function<? super T, ? extends R> mapper). Its mapper can return any value, including a collection or another stream; map() does not automatically unpack that result. For example, if nested is a List<List<Integer>>, nested.stream().map(List::stream) produces a Stream<Stream<Integer>>, not a Stream<Integer>. Similarly, mapping each list to itself retains a Stream<List<Integer>>. This is useful when the grouping is meaningful, but unsuitable when the next operation should work directly on individual integers.
The signature of flatMap() is <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper). Its mapper must return a stream of values rather than just a collection. With List<List<Integer>> nested = List.of(List.of(1, 2), List.of(3, 4)), nested.stream().flatMap(List::stream).collect(Collectors.toList()) produces [1, 2, 3, 4]. Each inner list becomes a stream, and its elements flow into the downstream pipeline. An empty inner stream contributes no elements. A null stream returned by the mapper is treated as empty, although explicitly returning Stream.empty() communicates intent more clearly.
Both methods are lazy intermediate operations: they build a pipeline, and processing begins when a terminal operation requests results. Flattening does not inherently create an intermediate combined list; downstream operations consume the flattened elements. Each mapped stream is closed after its contents are processed. Interviewers typically check whether you can predict the resulting stream type, explain the cardinality difference, and choose between preserving groups and processing their contents individually.
Key points to remember
- map() produces one result per input; that result may itself be a collection or stream.
- flatMap() maps each input to a stream and flattens one nesting level.
- map(List::stream) produces nested streams; flatMap(List::stream) produces a stream of list elements.
- Both are lazy intermediate operations and need a terminal operation to drive processing.
- flatMap() does not sort or remove duplicates; use sorted() or distinct() separately.
Common mistakes candidates make
- Assuming map() automatically flattens a returned collection or stream.
- Returning a List from a flatMap() mapper instead of converting it to a stream.
- Claiming flatMap() recursively removes all nesting levels or removes duplicate values.
Likely follow-up questions
Does flatMap() preserve element order?
For an ordered outer stream with ordered inner streams, flatMap() preserves their encounter order. Parallel forEach() may still display results out of order; use forEachOrdered() when ordered consumption matters.
How do mapToInt() and flatMapToInt() differ?
mapToInt() converts each input into one primitive int, producing an IntStream. flatMapToInt() converts each input into an IntStream and flattens the results, which is useful for a stream of int arrays using flatMapToInt(Arrays::stream).
How are map() and flatMap() different for Optional?
Optional.map() wraps a non-null mapper result in an Optional, so a mapper returning Optional<U> creates Optional<Optional<U>>. Optional.flatMap() expects an Optional-returning mapper and returns that Optional without an additional wrapper.
Interview tip: Explain the one-to-one versus one-to-many distinction, then show the resulting types for map(List::stream) and flatMap(List::stream).