Add PropertyMapper.to(...) API designed for immutable instances

spring-boot-project/spring-boot/src/main/java/org/springframework/boot/context/properties/PropertyMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2021 the original author or authors.
+ * Copyright 2012-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,11 +18,13 @@
 
 import java.util.NoSuchElementException;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 import org.springframework.util.function.SingletonSupplier;
@@ -52,6 +54,7 @@
  *
  * @author Phillip Webb
  * @author Artsiom Yudovin
+ * @author Chris Bono
  * @since 2.0.0
  */
 public final class PropertyMapper {
@@ -300,10 +303,29 @@ public void to(Consumer<T> consumer) {
 		 * @throws NoSuchElementException if the value has been filtered
 		 */
 		public <R> R toInstance(Function<T, R> factory) {
+			return toInstance(factory, true);
+		}
+
+		/**
+		 * Complete the mapping by creating a new instance from the non-filtered value.
+		 * @param <R> the resulting type
+		 * @param factory the factory used to create the instance
+		 * @param failIfFiltered whether to throw exception or return {@code null} if the
+		 * value has been filtered
+		 * @return the instance or {@code null} if the value has been filtered and
+		 * {@code failIfFiltered} is {@code false}
+		 * @throws NoSuchElementException if the value has been filtered and
+		 * {@code failIfFiltered} is {@code true}
+		 */
+		@Nullable
+		public <R> R toInstance(Function<T, R> factory, boolean failIfFiltered) {
 			Assert.notNull(factory, "Factory must not be null");
 			T value = this.supplier.get();
 			if (!this.predicate.test(value)) {
-				throw new NoSuchElementException("No value present");
+				if (failIfFiltered) {
+					throw new NoSuchElementException("No value present");
+				}
+				return null;
 			}
 			return factory.apply(value);
 		}

spring-boot-project/spring-boot/src/test/java/org/springframework/boot/context/properties/PropertyMapperTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,7 @@
  *
  * @author Phillip Webb
  * @author Artsiom Yudovin
+ * @author Chris Bono
  */
 class PropertyMapperTests {
 
@@ -207,6 +208,24 @@ void whenWhenValueMatchesShouldSupportChainedCalls() {
 		assertThat(result).isEqualTo("123");
 	}
 
+	@Test
+	void toInstanceWithoutFailFlagWithNonFilteredValueShouldReturnFactoryValue() {
+		String result = this.map.from("123").whenEqualTo("123").toInstance(String::new, false);
+		assertThat(result).isEqualTo("123");
+	}
+
+	@Test
+	void toInstanceWithoutFailFlagWithNonFilteredValueShouldTolerateNullFactoryValue() {
+		String result = this.map.from("123").whenEqualTo("123").toInstance((s) -> null, false);
+		assertThat(result).isNull();
+	}
+
+	@Test
+	void toInstanceWithoutFailFlagWithFilteredValueShouldReturnNull() {
+		String result = this.map.from("123").whenEqualTo("foo").toInstance(String::new, false);
+		assertThat(result).isNull();
+	}
+
 	static class Count<T> implements Supplier<T> {
 
 		private final Supplier<T> source;