Add bindOrCreate for constructor based binding

Deprecate the existing `BindResult.orElseCreate` method in favor of
`bindOrCreate` methods on the `Binder`. These new methods allow us to
implement custom creation logic depending on the type of object being
bound. Specifically, it allows constructor based binding to create new
instances that respect the `@DefaultValue` annotations.

Closes gh-17098

Co-authored-by: Phillip Webb <[email protected]>

Author: mbhave

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/template/PathBasedTemplateAvailabilityProvider.java

@@ -53,8 +53,7 @@ public boolean isTemplateAvailable(String view, Environment environment, ClassLo
 			ResourceLoader resourceLoader) {
 		if (ClassUtils.isPresent(this.className, classLoader)) {
 			Binder binder = Binder.get(environment);
-			TemplateAvailabilityProperties properties = binder.bind(this.propertyPrefix, this.propertiesClass)
-					.orElseCreate(this.propertiesClass);
+			TemplateAvailabilityProperties properties = binder.bindOrCreate(this.propertyPrefix, this.propertiesClass);
 			return isTemplateAvailable(view, resourceLoader, properties);
 		}
 		return false;

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

@@ -55,7 +55,7 @@ private static <T> Supplier<T> createBean(ConfigurableListableBeanFactory beanFa
 			ConfigurationPropertiesBinder binder = beanFactory.getBean(ConfigurationPropertiesBinder.BEAN_NAME,
 					ConfigurationPropertiesBinder.class);
 			try {
-				return binder.bind(bindable).orElseCreate(type);
+				return binder.bindOrCreate(bindable);
 			}
 			catch (Exception ex) {
 				throw new ConfigurationPropertiesBindException(beanName, type, annotation, ex);

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

@@ -86,11 +86,21 @@ public void setApplicationContext(ApplicationContext applicationContext) throws
 	}
 
 	public <T> BindResult<T> bind(Bindable<T> target) {
+		ConfigurationProperties annotation = getAnnotation(target);
+		BindHandler bindHandler = getBindHandler(target, annotation);
+		return getBinder().bind(annotation.prefix(), target, bindHandler);
+	}
+
+	public <T> T bindOrCreate(Bindable<T> target) {
+		ConfigurationProperties annotation = getAnnotation(target);
+		BindHandler bindHandler = getBindHandler(target, annotation);
+		return getBinder().bindOrCreate(annotation.prefix(), target, bindHandler);
+	}
+
+	private <T> ConfigurationProperties getAnnotation(Bindable<?> target) {
 		ConfigurationProperties annotation = target.getAnnotation(ConfigurationProperties.class);
 		Assert.state(annotation != null, () -> "Missing @ConfigurationProperties on " + target);
-		List<Validator> validators = getValidators(target);
-		BindHandler bindHandler = getBindHandler(annotation, validators);
-		return getBinder().bind(annotation.prefix(), target, bindHandler);
+		return annotation;
 	}
 
 	private Validator getConfigurationPropertiesValidator(ApplicationContext applicationContext,
@@ -101,6 +111,25 @@ private Validator getConfigurationPropertiesValidator(ApplicationContext applica
 		return null;
 	}
 
+	private <T> BindHandler getBindHandler(Bindable<T> target, ConfigurationProperties annotation) {
+		List<Validator> validators = getValidators(target);
+		BindHandler handler = new IgnoreTopLevelConverterNotFoundBindHandler();
+		if (annotation.ignoreInvalidFields()) {
+			handler = new IgnoreErrorsBindHandler(handler);
+		}
+		if (!annotation.ignoreUnknownFields()) {
+			UnboundElementsSourceFilter filter = new UnboundElementsSourceFilter();
+			handler = new NoUnboundElementsBindHandler(handler, filter);
+		}
+		if (!validators.isEmpty()) {
+			handler = new ValidationBindHandler(handler, validators.toArray(new Validator[0]));
+		}
+		for (ConfigurationPropertiesBindHandlerAdvisor advisor : getBindHandlerAdvisors()) {
+			handler = advisor.apply(handler);
+		}
+		return handler;
+	}
+
 	private List<Validator> getValidators(Bindable<?> target) {
 		List<Validator> validators = new ArrayList<>(3);
 		if (this.configurationPropertiesValidator != null) {
@@ -122,24 +151,6 @@ private Validator getJsr303Validator() {
 		return this.jsr303Validator;
 	}
 
-	private BindHandler getBindHandler(ConfigurationProperties annotation, List<Validator> validators) {
-		BindHandler handler = new IgnoreTopLevelConverterNotFoundBindHandler();
-		if (annotation.ignoreInvalidFields()) {
-			handler = new IgnoreErrorsBindHandler(handler);
-		}
-		if (!annotation.ignoreUnknownFields()) {
-			UnboundElementsSourceFilter filter = new UnboundElementsSourceFilter();
-			handler = new NoUnboundElementsBindHandler(handler, filter);
-		}
-		if (!validators.isEmpty()) {
-			handler = new ValidationBindHandler(handler, validators.toArray(new Validator[0]));
-		}
-		for (ConfigurationPropertiesBindHandlerAdvisor advisor : getBindHandlerAdvisors()) {
-			handler = advisor.apply(handler);
-		}
-		return handler;
-	}
-
 	private List<ConfigurationPropertiesBindHandlerAdvisor> getBindHandlerAdvisors() {
 		return this.applicationContext.getBeanProvider(ConfigurationPropertiesBindHandlerAdvisor.class).orderedStream()
 				.collect(Collectors.toList());

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

@@ -39,4 +39,13 @@ interface BeanBinder {
 	 */
 	<T> T bind(ConfigurationPropertyName name, Bindable<T> target, Context context, BeanPropertyBinder propertyBinder);
 
+	/**
+	 * Return a new instance for the specified type.
+	 * @param type the type used for creating a new instance
+	 * @param context the bind context
+	 * @param <T> the source type
+	 * @return the created instance
+	 */
+	<T> T create(Class<T> type, Context context);
+
 }

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

@@ -60,10 +60,25 @@ default Object onSuccess(ConfigurationPropertyName name, Bindable<?> target, Bin
 		return result;
 	}
 
+	/**
+	 * Called when binding of an element ends with an unbound result and a newly created
+	 * instance is about to be returned. Implementations may change the ultimately
+	 * returned result or perform addition validation.
+	 * @param name the name of the element being bound
+	 * @param target the item being bound
+	 * @param context the bind context
+	 * @param result the newly created instance (never {@code null})
+	 * @return the actual result that should be used (must not be {@code null})
+	 * @since 2.2.2
+	 */
+	default Object onCreate(ConfigurationPropertyName name, Bindable<?> target, BindContext context, Object result) {
+		return result;
+	}
+
 	/**
 	 * Called when binding fails for any reason (including failures from
-	 * {@link #onSuccess} calls). Implementations may choose to swallow exceptions and
-	 * return an alternative result.
+	 * {@link #onSuccess} or {@link #onCreate} calls). Implementations may choose to
+	 * swallow exceptions and return an alternative result.
 	 * @param name the name of the element being bound
 	 * @param target the item being bound
 	 * @param context the bind context

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

@@ -118,7 +118,9 @@ public T orElseGet(Supplier<? extends T> other) {
 	 * value has been bound.
 	 * @param type the type to create if no value was bound
 	 * @return the value, if bound, otherwise a new instance of {@code type}
+	 * @deprecated since 2.2.0 in favor of {@link Binder#bindOrCreate}
 	 */
+	@Deprecated
 	public T orElseCreate(Class<? extends T> type) {
 		Assert.notNull(type, "Type must not be null");
 		return (this.value != null) ? this.value : BeanUtils.instantiateClass(type);

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

@@ -17,19 +17,16 @@
 package org.springframework.boot.context.properties.bind;
 
 import java.util.ArrayDeque;
-import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.Deque;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Set;
 import java.util.function.Consumer;
 import java.util.function.Supplier;
-import java.util.stream.Stream;
 
 import org.springframework.beans.PropertyEditorRegistry;
 import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
@@ -58,14 +55,7 @@ public class Binder {
 	private static final Set<Class<?>> NON_BEAN_CLASSES = Collections
 			.unmodifiableSet(new HashSet<>(Arrays.asList(Object.class, Class.class)));
 
-	private static final List<BeanBinder> BEAN_BINDERS;
-
-	static {
-		List<BeanBinder> binders = new ArrayList<>();
-		binders.add(new ConstructorParametersBinder());
-		binders.add(new JavaBeanBinder());
-		BEAN_BINDERS = Collections.unmodifiableList(binders);
-	}
+	private static final BeanBinder[] BEAN_BINDERS = { new ConstructorParametersBinder(), new JavaBeanBinder() };
 
 	private final Iterable<ConfigurationPropertySource> sources;
 
@@ -196,40 +186,122 @@ public <T> BindResult<T> bind(String name, Bindable<T> target, BindHandler handl
 	 * @return the binding result (never {@code null})
 	 */
 	public <T> BindResult<T> bind(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler) {
+		T bound = bind(name, target, handler, false);
+		return BindResult.of(bound);
+	}
+
+	/**
+	 * Bind the specified target {@link Class} using this binder's
+	 * {@link ConfigurationPropertySource property sources} or create a new instance using
+	 * the type of the {@link Bindable} if the result of the binding is {@code null}.
+	 * @param name the configuration property name to bind
+	 * @param target the target class
+	 * @param <T> the bound type
+	 * @return the bound or created object
+	 * @since 2.2.0
+	 * @see #bind(ConfigurationPropertyName, Bindable, BindHandler)
+	 */
+	public <T> T bindOrCreate(String name, Class<T> target) {
+		return bindOrCreate(name, Bindable.of(target));
+	}
+
+	/**
+	 * Bind the specified target {@link Bindable} using this binder's
+	 * {@link ConfigurationPropertySource property sources} or create a new instance using
+	 * the type of the {@link Bindable} if the result of the binding is {@code null}.
+	 * @param name the configuration property name to bind
+	 * @param target the target bindable
+	 * @param <T> the bound type
+	 * @return the bound or created object
+	 * @since 2.2.0
+	 * @see #bindOrCreate(ConfigurationPropertyName, Bindable, BindHandler)
+	 */
+	public <T> T bindOrCreate(String name, Bindable<T> target) {
+		return bindOrCreate(ConfigurationPropertyName.of(name), target, null);
+	}
+
+	/**
+	 * Bind the specified target {@link Bindable} using this binder's
+	 * {@link ConfigurationPropertySource property sources} or create a new instance using
+	 * the type of the {@link Bindable} if the result of the binding is {@code null}.
+	 * @param name the configuration property name to bind
+	 * @param target the target bindable
+	 * @param handler the bind handler
+	 * @param <T> the bound type
+	 * @return the bound or created object
+	 * @since 2.2.0
+	 * @see #bindOrCreate(ConfigurationPropertyName, Bindable, BindHandler)
+	 */
+	public <T> T bindOrCreate(String name, Bindable<T> target, BindHandler handler) {
+		return bindOrCreate(ConfigurationPropertyName.of(name), target, handler);
+	}
+
+	/**
+	 * Bind the specified target {@link Bindable} using this binder's
+	 * {@link ConfigurationPropertySource property sources} or create a new instance using
+	 * the type of the {@link Bindable} if the result of the binding is {@code null}.
+	 * @param name the configuration property name to bind
+	 * @param target the target bindable
+	 * @param handler the bind handler (may be {@code null})
+	 * @param <T> the bound or created type
+	 * @since 2.2.0
+	 * @return the bound or created object
+	 */
+	public <T> T bindOrCreate(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler) {
+		return bind(name, target, handler, true);
+	}
+
+	private <T> T bind(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler, boolean create) {
 		Assert.notNull(name, "Name must not be null");
 		Assert.notNull(target, "Target must not be null");
 		handler = (handler != null) ? handler : BindHandler.DEFAULT;
 		Context context = new Context();
-		T bound = bind(name, target, handler, context, false);
-		return BindResult.of(bound);
+		return bind(name, target, handler, context, false, create);
 	}
 
-	protected final <T> T bind(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler, Context context,
-			boolean allowRecursiveBinding) {
+	private <T> T bind(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler, Context context,
+			boolean allowRecursiveBinding, boolean create) {
 		context.clearConfigurationProperty();
 		try {
 			target = handler.onStart(name, target, context);
 			if (target == null) {
-				return null;
+				return handleBindResult(name, target, handler, context, null, create);
 			}
 			Object bound = bindObject(name, target, handler, context, allowRecursiveBinding);
-			return handleBindResult(name, target, handler, context, bound);
+			return handleBindResult(name, target, handler, context, bound, create);
 		}
 		catch (Exception ex) {
 			return handleBindError(name, target, handler, context, ex);
 		}
 	}
 
 	private <T> T handleBindResult(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler,
-			Context context, Object result) throws Exception {
+			Context context, Object result, boolean create) throws Exception {
 		if (result != null) {
 			result = handler.onSuccess(name, target, context, result);
 			result = context.getConverter().convert(result, target);
 		}
+		if (result == null && create) {
+			result = createBean(target, context);
+			result = handler.onCreate(name, target, context, result);
+			result = context.getConverter().convert(result, target);
+			Assert.state(result != null, () -> "Unable to create instance for " + target.getType());
+		}
 		handler.onFinish(name, target, context, result);
 		return context.getConverter().convert(result, target);
 	}
 
+	private Object createBean(Bindable<?> target, Context context) {
+		Class<?> type = target.getType().resolve();
+		for (BeanBinder beanBinder : BEAN_BINDERS) {
+			Object bean = beanBinder.create(type, context);
+			if (bean != null) {
+				return bean;
+			}
+		}
+		return null;
+	}
+
 	private <T> T handleBindError(ConfigurationPropertyName name, Bindable<T> target, BindHandler handler,
 			Context context, Exception error) {
 		try {
@@ -288,7 +360,7 @@ private <T> Object bindAggregate(ConfigurationPropertyName name, Bindable<T> tar
 			Context context, AggregateBinder<?> aggregateBinder) {
 		AggregateElementBinder elementBinder = (itemName, itemTarget, source) -> {
 			boolean allowRecursiveBinding = aggregateBinder.isAllowRecursiveBinding(source);
-			Supplier<?> supplier = () -> bind(itemName, itemTarget, handler, context, allowRecursiveBinding);
+			Supplier<?> supplier = () -> bind(itemName, itemTarget, handler, context, allowRecursiveBinding, false);
 			return context.withSource(source, supplier);
 		};
 		return context.withIncreasedDepth(() -> aggregateBinder.bind(name, target, elementBinder));
@@ -325,10 +397,15 @@ private Object bindBean(ConfigurationPropertyName name, Bindable<?> target, Bind
 			return null;
 		}
 		BeanPropertyBinder propertyBinder = (propertyName, propertyTarget) -> bind(name.append(propertyName),
-				propertyTarget, handler, context, false);
+				propertyTarget, handler, context, false, false);
 		return context.withBean(type, () -> {
-			Stream<?> boundBeans = BEAN_BINDERS.stream().map((b) -> b.bind(name, target, context, propertyBinder));
-			return boundBeans.filter(Objects::nonNull).findFirst().orElse(null);
+			for (BeanBinder beanBinder : BEAN_BINDERS) {
+				Object bean = beanBinder.bind(name, target, context, propertyBinder);
+				if (bean != null) {
+					return bean;
+				}
+			}
+			return null;
 		});
 	}
 

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

@@ -57,20 +57,45 @@ public <T> T bind(ConfigurationPropertyName name, Bindable<T> target, Binder.Con
 			return null;
 		}
 		List<Object> bound = bind(propertyBinder, bean, context.getConverter());
-		return (T) BeanUtils.instantiateClass(bean.getConstructor(), bound.toArray());
+		return (bound != null) ? (T) BeanUtils.instantiateClass(bean.getConstructor(), bound.toArray()) : null;
+	}
+
+	@Override
+	@SuppressWarnings("unchecked")
+	public <T> T create(Class<T> type, Binder.Context context) {
+		Bean bean = getBean(type);
+		if (bean == null) {
+			return null;
+		}
+		Collection<ConstructorParameter> parameters = bean.getParameters().values();
+		List<Object> parameterValues = new ArrayList<>(parameters.size());
+		for (ConstructorParameter parameter : parameters) {
+			Object boundParameter = getDefaultValue(parameter, context.getConverter());
+			parameterValues.add(boundParameter);
+		}
+		return (T) BeanUtils.instantiateClass(bean.getConstructor(), parameterValues.toArray());
+	}
+
+	private <T> Bean getBean(Class<T> type) {
+		if (KOTLIN_PRESENT && KotlinDetector.isKotlinType(type)) {
+			return KotlinBeanProvider.get(type);
+		}
+		return SimpleBeanProvider.get(type);
 	}
 
 	private List<Object> bind(BeanPropertyBinder propertyBinder, Bean bean, BindConverter converter) {
 		Collection<ConstructorParameter> parameters = bean.getParameters().values();
 		List<Object> boundParameters = new ArrayList<>(parameters.size());
+		int unboundParameterCount = 0;
 		for (ConstructorParameter parameter : parameters) {
 			Object boundParameter = bind(parameter, propertyBinder);
 			if (boundParameter == null) {
+				unboundParameterCount++;
 				boundParameter = getDefaultValue(parameter, converter);
 			}
 			boundParameters.add(boundParameter);
 		}
-		return boundParameters;
+		return (unboundParameterCount != parameters.size()) ? boundParameters : null;
 	}
 
 	private Object getDefaultValue(ConstructorParameter parameter, BindConverter converter) {