Add support for configuration properties scanning

See gh-12602

Author: mbhave

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

@@ -25,6 +25,7 @@
 
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.context.TypeExcludeFilter;
+import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.ComponentScan;
 import org.springframework.context.annotation.ComponentScan.Filter;
@@ -35,9 +36,11 @@
 /**
  * Indicates a {@link Configuration configuration} class that declares one or more
  * {@link Bean @Bean} methods and also triggers {@link EnableAutoConfiguration
- * auto-configuration} and {@link ComponentScan component scanning}. This is a convenience
- * annotation that is equivalent to declaring {@code @Configuration},
- * {@code @EnableAutoConfiguration} and {@code @ComponentScan}.
+ * auto-configuration}, {@link ComponentScan component scanning}, and
+ * {@link ConfigurationPropertiesScan configuration properties scanning}. This is a
+ * convenience annotation that is equivalent to declaring {@code @Configuration},
+ * {@code @EnableAutoConfiguration}, {@code @ComponentScan}, and
+ * {@code @ConfigurationPropertiesScan}.
  *
  * @author Phillip Webb
  * @author Stephane Nicoll
@@ -50,6 +53,7 @@
 @Inherited
 @SpringBootConfiguration
 @EnableAutoConfiguration
+@ConfigurationPropertiesScan
 @ComponentScan(excludeFilters = {
 		@Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
 		@Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class) })

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -1070,7 +1070,23 @@ missing property.
 [[boot-features-external-config-enabling]]
 ==== Enabling `@ConfigurationProperties`-annotated types
 Spring Boot provides an infrastructure to bind such types and register them as beans
-automatically. Any `@Configuration` class can specify the list of types to process as
+automatically. If your application uses `@SpringBootApplication`, classes annotated with
+`@ConfigurationProperties` will automatically be scanned and registered as beans. By default,
+scanning will occur from the package of the class that declares this annotation. If you want
+to define specific packages to scan, you can do so using an explicit `@ConfigurationPropertiesScan`
+directive on your `@SpringBootApplication`-annotated class as shown in the following example:
+
+[source,java,indent=0]
+----
+	@SpringBootApplication
+	@ConfigurationPropertiesScan({ "com.example.app", "org.acme.another" })
+	public class MyApplication {
+	}
+----
+
+Sometimes, classes annotated with `@ConfigurationProperties` might not be suitable
+for scanning, for example, if you're developing your own auto-configuration. In these
+cases, you can specify the list of types to process on any `@Configuration` class as
 shown in the following example:
 
 [source,java,indent=0]
@@ -1083,13 +1099,13 @@ shown in the following example:
 
 [NOTE]
 ====
-When the `@ConfigurationProperties` bean is registered that way, the bean has a
-conventional name: `<prefix>-<fqn>`, where `<prefix>` is the environment key prefix
-specified in the `@ConfigurationProperties` annotation and `<fqn>` is the fully qualified
-name of the bean. If the annotation does not provide any prefix, only the fully qualified
-name of the bean is used.
+When the `@ConfigurationProperties` bean is registered using scanning or via
+`@EnableConfigurationProperties`, the bean has a conventional name: `<prefix>-<fqn>`,
+where `<prefix>` is the environment key prefix specified in the `@ConfigurationProperties`
+annotation and `<fqn>` is the fully qualified name of the bean. If the annotation does not
+provide any prefix, only the fully qualified name of the bean is used.
 
-The bean name in the examples above is `acme-com.example.AcmeProperties`.
+The bean name in the example above is `acme-com.example.AcmeProperties`.
 ====
 
 We recommend that `@ConfigurationProperties` only deal with the environment and, in
@@ -1100,27 +1116,10 @@ binder that only deals with the environment.
 For corner cases, setter injection can be used or any of the `*Aware` interfaces provided
 by the framework (such as `EnvironmentAware` if you need access to the `Environment`).
 
-If you find using `@EnableConfigurationProperties` tedious, you can also declare a bean
-yourself. For instance, instead of annotating `MyConfiguration` with
-`@EnableConfigurationProperties(AcmeProperties.class)`, you could make `AcmeProperties`
-a bean, as shown in the following example:
-
-[source,java,indent=0]
-----
-	@Component
-	@ConfigurationProperties(prefix="acme")
-	public class AcmeProperties {
-
-			private boolean enabled;
-
-    		private InetAddress remoteAddress;
-
-    		private final Security security = new Security();
-
-			// ... see the preceding JavaBean properties binding example
-
-	}
-----
+NOTE: Annotating a `@ConfigurationProperties` type with `@Component` will result in two
+beans of the same type if the type is also scanned as part of classpath scanning. If you want
+to register the bean yourself using `@Component`, consider disabling scanning of
+`@ConfigurationProperties`.
 
 
 

spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

@@ -336,8 +336,8 @@ best practices that help.
 When a class does not include a `package` declaration, it is considered to be in the
 "`default package`". The use of the "`default package`" is generally discouraged and
 should be avoided. It can cause particular problems for Spring Boot applications that use
-the `@ComponentScan`, `@EntityScan`, or `@SpringBootApplication` annotations, since every
-class from every jar is read.
+the `@ComponentScan`, `@ConfigurationPropertiesScan`, `@EntityScan`, or `@SpringBootApplication`
+annotations, since every class from every jar is read.
 
 TIP: We recommend that you follow Java's recommended package naming conventions and use a
 reversed domain name (for example, `com.example.project`).
@@ -355,8 +355,8 @@ is used to search for `@Entity` items. Using a root package also allows componen
 scan to apply only on your project.
 
 TIP: If you don't want to use `@SpringBootApplication`, the `@EnableAutoConfiguration`
-and `@ComponentScan` annotations that it imports defines that behaviour so you can also
-use that instead.
+`@ComponentScan`, and `@ConfigurationPropertiesScan` annotations that it imports defines
+that behaviour so you can also use those instead.
 
 The following listing shows a typical layout:
 
@@ -556,12 +556,14 @@ be able to define extra configuration on their "application class". A single
 auto-configuration mechanism>>
 * `@ComponentScan`: enable `@Component` scan on the package where the application is
 located (see <<using-boot-structuring-your-code,the best practices>>)
+* `@ConfigurationPropertiesScan`: enable `@ConfigurationProperties` scan on the package
+where the application is located (see <<using-boot-structuring-your-code,the best practices>>)
 * `@Configuration`: allow to register extra beans in the context or import additional
 configuration classes
 
 The `@SpringBootApplication` annotation is equivalent to using `@Configuration`,
-`@EnableAutoConfiguration`, and `@ComponentScan` with their default attributes, as shown
-in the following example:
+`@EnableAutoConfiguration`, @ComponentScan`, and `@ConfigurationPropertiesScan` with their default
+attributes, as shown in the following example:
 
 
 [source,java,indent=0]
@@ -571,7 +573,7 @@ in the following example:
 	import org.springframework.boot.SpringApplication;
 	import org.springframework.boot.autoconfigure.SpringBootApplication;
 
-	@SpringBootApplication // same as @Configuration @EnableAutoConfiguration @ComponentScan
+	@SpringBootApplication // same as @Configuration @EnableAutoConfiguration @ComponentScan @ConfigurationPropertiesScan
 	public class Application {
 
 		public static void main(String[] args) {
@@ -588,7 +590,7 @@ NOTE: `@SpringBootApplication` also provides aliases to customize the attributes
 ====
 None of these features are mandatory and you may choose to replace this single annotation
 by any of the features that it enables. For instance, you may not want to use component
-scan in your application:
+scan or configuration properties scan in your application:
 
 [source,java,indent=0]
 ----
@@ -612,8 +614,8 @@ scan in your application:
 ----
 
 In this example, `Application` is just like any other Spring Boot application except that
-`@Component`-annotated classes are not detected automatically and the user-defined beans
-are imported explicitly (see `@Import`).
+`@Component`-annotated classes and `@ConfigurationProperties`-annotated classes are not detected
+automatically and the user-defined beans are imported explicitly (see `@Import`).
 ====
 
 

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

@@ -0,0 +1,120 @@
+/*
+ * Copyright 2012-2019 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.boot.context.properties;
+
+import java.lang.reflect.Constructor;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.beans.factory.support.GenericBeanDefinition;
+import org.springframework.core.KotlinDetector;
+import org.springframework.core.annotation.AnnotationUtils;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+
+/**
+ * Registers a bean definition for a type annotated with {@link ConfigurationProperties}
+ * using the prefix of the annotation in the bean name.
+ *
+ * @author Madhura Bhave
+ */
+final class ConfigurationPropertiesBeanDefinitionRegistrar {
+
+	private ConfigurationPropertiesBeanDefinitionRegistrar() {
+	}
+
+	private static final boolean KOTLIN_PRESENT = KotlinDetector.isKotlinPresent();
+
+	public static void register(BeanDefinitionRegistry registry,
+			ConfigurableListableBeanFactory beanFactory, Class<?> type) {
+		String name = getName(type);
+		if (!containsBeanDefinition(beanFactory, name)) {
+			registerBeanDefinition(registry, beanFactory, name, type);
+		}
+	}
+
+	private static String getName(Class<?> type) {
+		ConfigurationProperties annotation = AnnotationUtils.findAnnotation(type,
+				ConfigurationProperties.class);
+		String prefix = (annotation != null) ? annotation.prefix() : "";
+		return (StringUtils.hasText(prefix) ? prefix + "-" + type.getName()
+				: type.getName());
+	}
+
+	private static boolean containsBeanDefinition(
+			ConfigurableListableBeanFactory beanFactory, String name) {
+		if (beanFactory.containsBeanDefinition(name)) {
+			return true;
+		}
+		BeanFactory parent = beanFactory.getParentBeanFactory();
+		if (parent instanceof ConfigurableListableBeanFactory) {
+			return containsBeanDefinition((ConfigurableListableBeanFactory) parent, name);
+		}
+		return false;
+	}
+
+	private static void registerBeanDefinition(BeanDefinitionRegistry registry,
+			ConfigurableListableBeanFactory beanFactory, String name, Class<?> type) {
+		assertHasAnnotation(type);
+		registry.registerBeanDefinition(name,
+				createBeanDefinition(beanFactory, name, type));
+	}
+
+	private static void assertHasAnnotation(Class<?> type) {
+		Assert.notNull(
+				AnnotationUtils.findAnnotation(type, ConfigurationProperties.class),
+				() -> "No " + ConfigurationProperties.class.getSimpleName()
+						+ " annotation found on  '" + type.getName() + "'.");
+	}
+
+	private static BeanDefinition createBeanDefinition(
+			ConfigurableListableBeanFactory beanFactory, String name, Class<?> type) {
+		if (canBindAtCreationTime(type)) {
+			return ConfigurationPropertiesBeanDefinition.from(beanFactory, name, type);
+		}
+		else {
+			GenericBeanDefinition definition = new GenericBeanDefinition();
+			definition.setBeanClass(type);
+			return definition;
+		}
+	}
+
+	private static boolean canBindAtCreationTime(Class<?> type) {
+		List<Constructor<?>> constructors = determineConstructors(type);
+		return (constructors.size() == 1 && constructors.get(0).getParameterCount() > 0);
+	}
+
+	private static List<Constructor<?>> determineConstructors(Class<?> type) {
+		List<Constructor<?>> constructors = new ArrayList<>();
+		if (KOTLIN_PRESENT && KotlinDetector.isKotlinType(type)) {
+			Constructor<?> primaryConstructor = BeanUtils.findPrimaryConstructor(type);
+			if (primaryConstructor != null) {
+				constructors.add(primaryConstructor);
+			}
+		}
+		else {
+			constructors.addAll(Arrays.asList(type.getDeclaredConstructors()));
+		}
+		return constructors;
+	}
+
+}

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

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2012-2019 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.boot.context.properties;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.context.annotation.Import;
+import org.springframework.core.annotation.AliasFor;
+
+/**
+ * Configures the base packages used when scanning for {@link ConfigurationProperties}
+ * classes. One of {@link #basePackageClasses()}, {@link #basePackages()} or its alias
+ * {@link #value()} may be specified to define specific packages to scan. If specific
+ * packages are not defined scanning will occur from the package of the class with this
+ * annotation.
+ *
+ * @author Madhura Bhave
+ * @since 2.2.0
+ * @see ConfigurationPropertiesScanRegistrar
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Import(ConfigurationPropertiesScanRegistrar.class)
+public @interface ConfigurationPropertiesScan {
+
+	/**
+	 * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation
+	 * declarations e.g.: {@code @ConfigurationPropertiesScan("org.my.pkg")} instead of
+	 * {@code @ConfigurationPropertiesScan(basePackages="org.my.pkg")}.
+	 * @return the base packages to scan
+	 */
+	@AliasFor("basePackages")
+	String[] value() default {};
+
+	/**
+	 * Base packages to scan for configuration properties. {@link #value()} is an alias
+	 * for (and mutually exclusive with) this attribute.
+	 * <p>
+	 * Use {@link #basePackageClasses()} for a type-safe alternative to String-based
+	 * package names.
+	 * @return the base packages to scan
+	 */
+	@AliasFor("value")
+	String[] basePackages() default {};
+
+	/**
+	 * Type-safe alternative to {@link #basePackages()} for specifying the packages to
+	 * scan for configuration properties. The package of each class specified will be
+	 * scanned.
+	 * <p>
+	 * Consider creating a special no-op marker class or interface in each package that
+	 * serves no purpose other than being referenced by this attribute.
+	 * @return classes from the base packages to scan
+	 */
+	Class<?>[] basePackageClasses() default {};
+
+}