Java Streams offer powerful ways to transform data, especially for one-to-many mappings. mapMulti, introduced in Java 16, provides an imperative alternative to the classic flatMap, optimizing performance by skipping intermediate Stream creation.

Core Distinctions

mapMulti uses a BiConsumer that receives the input element and a downstream Consumer, enabling direct emission of multiple (or zero) values without generating Streams per element. This reduces overhead, making it ideal for conditional expansions or small output sets. flatMap, in contrast, applies a Function returning a Stream for each input, then flattens them; it's elegant for functional styles but creates unnecessary Streams, even empties during filtering.

The imperative nature of mapMulti allows seamless integration of filtering and mapping logic in one step, streamlining pipelines.​

Practical Examples

Consider processing languages, expanding those containing 'o' to both original and uppercase forms.

With mapMulti (efficient, direct emission):

List<String> result = Stream.of("Java", "Groovy", "Clojure")
        .<String>mapMulti((lang, downstream) -> {
            if (lang.contains("o")) {
                downstream.accept(lang);
                downstream.accept(lang.toUpperCase());
            }
        })
        .toList();
IO.println(result);

With flatMap (functional, but with Stream overhead):

List<String> result = Stream.of("Java", "Groovy", "Clojure")
        .filter(lang -> lang.contains("o"))
        .flatMap(lang -> Stream.of(lang, lang.toUpperCase()))
        .toList();
IO.println(result);
// Output: ["Groovy", "GROOVY", "Clojure", "CLOJURE"]

Choosing the Right Tool

Select mapMulti for high-performance scenarios like microservices processing, where avoiding Stream instantiation boosts throughput, or for complex imperative conditions. Stick with flatMap for declarative codebases or transformations naturally producing Streams, such as string splitting.