Advantages of Stream#mapMulti ?

[Ron McLeod]

Java 16 added Stream#mapMulti.

It seems like one advantage of using this method over flatMap or a combination of filter and map is the reduction in the number of streams created; which probably translates into better performance.  Are there any other benefits?

var barriers = Arrays.asList("gate", "wall", null, "fence");

System.out.println("multiMap:");
barriers.stream()
        .mapMulti((item, consumer) -> {
            if (item != null) {
                consumer.accept(item.toUpperCase());
            }
        })
        .forEach(System.out::println);

System.out.println("filter and map:");
barriers.stream()
        .filter(Objects::nonNull)
        .map(String::toUpperCase)
        .forEach(System.out::println);

System.out.println("flatMap:");
barriers.stream()
        .flatMap(item -> (item != null)
                ? Stream.of(item.toUpperCase())
                : Stream.empty())
        .forEach(System.out::println);

multiMap: GATE WALL FENCE filter and map: GATE WALL FENCE flatMap: GATE WALL FENCE

[Stephan van Hulst]

The advantage of using mapMulti() over using filter() and map() is the same advantage that using flatMap() has: flatMap() and mapMulti() can both expand fewer elements into more elements, filter() can only reduce the number of elements.

For example, you can not use filter() and map() to expand a stream of countries into a stream of cities belonging to those countries.

So the comparison is really just between mapMulti() and flatMap(). Honestly, I can't say much more than what the Javadocs already say. Besides the performance benefit of avoiding a large number of streams, mapMulti() is useful if your mapping operation is more readable in imperative programming style.

Here is an example:

var capitalCities = countries.stream()
  .mapMulti((country, capitals) -> {
    country.officialCapital().ifPresent(capitals::accept);

    // Countries that have capitals in addition to the official capital
    capitals.accept(switch (country.name()) {
      case "Benin"       -> country.getCity("Cotonou"),
      case "Bolivia"     -> country.getCity("La Paz"),
      case "Eswatini"    -> country.getCity("Lobamba"),
      case "Malaysia"    -> country.getCity("Petrujaya"),
      case "Netherlands" -> country.getCity("Den Haag"),
      case "Sri Lanka"   -> country.getCity("Kotte")
    });

    // South Africa has no single official capital
    if (country.name().equals("South Africa")) {
      capitals.accept(country.getCity("Bloemfontein"));
      capitals.accept(country.getCity("Cape Town"));
      capitals.accept(country.getCity("Pretoria"));
    }
  })
  .toList();

This example benefits doubly: Most countries have exactly one capital city, which means flatMap() would have used a high ratio of streams to capitals. This example is also more readable in imperative style. I'll leave it up to you to write a version that uses flatMap().

In practice, I hardly ever encounter a situation where I'm tempted to use mapMulti(). I mostly design my classes in such a way that a declarative style is favoured:

var capitalCities = countries.stream()
  .flatMap(Country::capitals)
  .toList();

This doesn't get the performance benefit of mapMulti(), but in practice it doesn't matter.

If you can't or don't want to add a method capitals() to Country, then you might favour the mapMulti() approach.

[Ron McLeod]

Thanks for the example - it helped me realize that accept could be called more than once - that lets me avoid needing to collect downstream elements in a temporary collection when using flatMap.

For example - I have an annotation which defines what types of content a class can process:

public @interface SsiContentClass {
    public String contentClass();
    public String[] aliases() default {};
    public String metadataContentClass() default "";
}

In order to work-around some issues using Graalvm to create a native executable, I need to extract and transform to the information in annotations at Graalvm's build time.  For each annotation in, there could be multiple elements out.  In the example below, I collected the elements to a List, returned it as a stream, and then flattened it using flatMap:

private static Map<String, Class<? extends SsiObject>> contentClassMap = new HashMap<>();
static {
	record MappingRecord(String contentClass, Class<? extends SsiObject> clazz) {
		MappingRecord(Class<? extends SsiObject> clazz) {
			this(clazz.getAnnotation(SsiContentClass.class).contentClass(), clazz);
		}
	}

	var reflections = new Reflections(SsiObject.class.getPackageName());
	contentClassMap = reflections
			.getSubTypesOf(SsiObject.class).stream()
			.filter(cl -> cl.isAnnotationPresent(SsiContentClass.class))
			.flatMap(cl -> {
				var mappingRecords = new ArrayList<MappingRecord>();
				mappingRecords.add(new MappingRecord(cl));
				Arrays.stream(cl.getAnnotation(SsiContentClass.class).aliases())
						.forEach(contentClass -> mappingRecords.add(new MappingRecord(contentClass, cl)));
				return mappingRecords.stream();
			})
			.collect(Collectors.toMap(MappingRecord::contentClass, MappingRecord::clazz));
}

Using mapMulti, I can eliminate the List:

private static Map<String, Class<? extends SsiObject>> contentClassMap = new HashMap<>();
static {
	record MappingRecord(String contentClass, Class<? extends SsiObject> clazz) {
		MappingRecord(Class<? extends SsiObject> clazz) {
			this(clazz.getAnnotation(SsiContentClass.class).contentClass(), clazz);
		}
	}

	var reflections = new Reflections(SsiObject.class.getPackageName());
	contentClassMap = reflections
			.getSubTypesOf(SsiObject.class).stream()
			.<MappingRecord>mapMulti((cl, contentMapping) -> {
				if (cl.isAnnotationPresent(SsiContentClass.class)) {
					contentMapping.accept(new MappingRecord(cl));
					Arrays.stream(cl.getAnnotation(SsiContentClass.class).aliases())
							.forEach(contentClass -> contentMapping.accept(new MappingRecord(contentClass, cl)));
				}
			})
			.collect(Collectors.toMap(MappingRecord::contentClass, MappingRecord::clazz));
}

[Stephan van Hulst]

There is no need to call Arrays.stream():

  private static final Map<String, Class<? extends SsiObject>> CONTENT_CLASS_MAP;

  static {
    record MappingRecord(String contentClass, Class<? extends SsiObject> clazz) {

      private static void mapContentClasses(
        Class<? extends SsiObject> ssiType,
        Consumer<? super MappingRecord> contentMapping
      ) {
        var annotation = ssiType.getAnnotation(SsiContentClass.class);

        if (annotation != null) {
          contentMapping.accept(new MappingRecord(annotation.contentClass(), ssiType));
        
          for (var alias: annotation.aliases()) {
            contentMapping.accept(new MappingRecord(alias, ssiType));
          }
        }
      }
    }

    var reflections = new Reflections(SsiObject.class.getPackageName());

    CONTENT_CLASS_MAP = reflections
      .getSubTypesOf(SsiObject.class).stream()
      .mapMulti(MappingRecord::mapContentClasses)
      .collect(toMap(MappingRecord::contentClass, MappingRecord::clazz));
  }

[Liutauras Vilda]

Cowgratulations, Ron! Your topic has been published in our CodeRanch's February 2024 Edition Journal