From f55a6051dfe0ea51fc82196cb6ca3c9a4e1570ff Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 6 Sep 2018 18:36:49 +0200 Subject: [PATCH] Document default embedded value resolver support for property placeholders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spring 4.3 introduced support for registering a default embedded value resolver for the default environment, in case of none having been registered through post-processors (like PropertyPlaceholderConfigurer and PropertySourcesPlaceholderConfigurer. However, the existing documentation – stating that a static PropertySourcesPlaceholderConfigurer bean is required in order for values coming from @PropertySource declarations to be honored – was not updated to reflect the change. This commit addresses this by updating the JavaDoc for @Configuration and @PropertySource accordingly Issue: SPR-17212 --- .../context/annotation/Configuration.java | 26 ++++++++---- .../context/annotation/PropertySource.java | 40 +++++++++++-------- .../PropertySourcesPlaceholderConfigurer.java | 10 ++--- 3 files changed, 46 insertions(+), 30 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java index 5bb16354331..abdd2a44e31 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java @@ -162,8 +162,8 @@ import org.springframework.stereotype.Component; * *

Using the {@code @Value} annotation

* - *

Externalized values may be injected {@code @Configuration} classes using the - * {@link Value @Value} annotation: + *

Externalized values may be injected into {@code @Configuration} classes using + * the {@link Value @Value} annotation: * * 

  * @Configuration
@@ -178,13 +178,23 @@ import org.springframework.stereotype.Component;
  *     }
  * }
* - *

This approach is most useful when using Spring's + *

This approach is often used in conjunction with Spring's * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer - * PropertySourcesPlaceholderConfigurer}, usually enabled via XML with - * {@code }. See the section below on composing - * {@code @Configuration} classes with Spring XML using {@code @ImportResource}, - * see the {@link Value @Value} javadocs, and see the {@link Bean @Bean} javadocs for - * details on working with {@code BeanFactoryPostProcessor} types such as + * PropertySourcesPlaceholderConfigurer} that can be enabled automatically + * in XML configuration via {@code } or explicitly + * in a {@code @Configuration} class via a dedicated {@code static} {@code @Bean} method + * (see "a note on BeanFactoryPostProcessor-returning {@code @Bean} methods" of + * {@link Bean @Bean}'s javadocs for details). Note, however, that explicit registration + * of a {@code PropertySourcesPlaceholderConfigurer} via a {@code static} {@code @Bean} + * method is typically only required if you need to customize configuration such as the + * placeholder syntax, etc. Specifically, if no bean post-processor (such as a + * {@code PropertySourcesPlaceholderConfigurer}) has registered an embedded value + * resolver for the {@code ApplicationContext}, Spring will register a default + * embedded value resolver which resolves placeholders against property sources + * registered in the {@code Environment}. See the section below on composing + * {@code @Configuration} classes with Spring XML using {@code @ImportResource}; see + * the {@link Value @Value} javadocs; and see the {@link Bean @Bean} javadocs for details + * on working with {@code BeanFactoryPostProcessor} types such as * {@code PropertySourcesPlaceholderConfigurer}. * *

Composing {@code @Configuration} classes

diff --git a/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java b/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java index e2bf4129e77..9214b369a93 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java @@ -54,25 +54,30 @@ import org.springframework.core.io.support.PropertySourceFactory; * } * } * - * Notice that the {@code Environment} object is + *

Notice that the {@code Environment} object is * {@link org.springframework.beans.factory.annotation.Autowired @Autowired} into the * configuration class and then used when populating the {@code TestBean} object. Given * the configuration above, a call to {@code testBean.getName()} will return "myTestBean". * - *

Resolving ${...} placeholders in {@code } and {@code @Value} annotations

- * - * In order to resolve ${...} placeholders in {@code } definitions or {@code @Value} - * annotations using properties from a {@code PropertySource}, one must register - * a {@code PropertySourcesPlaceholderConfigurer}. This happens automatically when using - * {@code } in XML, but must be explicitly registered using - * a {@code static} {@code @Bean} method when using {@code @Configuration} classes. See - * the "Working with externalized values" section of @{@link Configuration}'s javadoc and - * "a note on BeanFactoryPostProcessor-returning @Bean methods" of @{@link Bean}'s javadoc - * for details and examples. + *

Resolving ${...} placeholders in {@code } and {@code @Value} annotations

+ * + *

In order to resolve ${...} placeholders in {@code } definitions or {@code @Value} + * annotations using properties from a {@code PropertySource}, you must ensure that an + * appropriate embedded value resolver is registered in the {@code BeanFactory} + * used by the {@code ApplicationContext}. This happens automatically when using + * {@code } in XML. When using {@code @Configuration} classes + * this can be achieved by explicitly registering a {@code PropertySourcesPlaceholderConfigurer} + * via a {@code static} {@code @Bean} method. Note, however, that explicit registration + * of a {@code PropertySourcesPlaceholderConfigurer} via a {@code static} {@code @Bean} + * method is typically only required if you need to customize configuration such as the + * placeholder syntax, etc. See the "Working with externalized values" section of + * {@link Configuration @Configuration}'s javadocs and "a note on + * BeanFactoryPostProcessor-returning {@code @Bean} methods" of {@link Bean @Bean}'s + * javadocs for details and examples. * *

Resolving ${...} placeholders within {@code @PropertySource} resource locations

* - * Any ${...} placeholders present in a {@code @PropertySource} {@linkplain #value() + *

Any ${...} placeholders present in a {@code @PropertySource} {@linkplain #value() * resource location} will be resolved against the set of property sources already * registered against the environment. For example: * @@ -92,7 +97,7 @@ import org.springframework.core.io.support.PropertySourceFactory; * } * } * - * Assuming that "my.placeholder" is present in one of the property sources already + *

Assuming that "my.placeholder" is present in one of the property sources already * registered, e.g. system properties or environment variables, the placeholder will * be resolved to the corresponding value. If not, then "default/path" will be used as a * default. Expressing a default value (delimited by colon ":") is optional. If no @@ -101,10 +106,10 @@ import org.springframework.core.io.support.PropertySourceFactory; * *

A note on property overriding with @PropertySource

* - * In cases where a given property key exists in more than one {@code .properties} + *

In cases where a given property key exists in more than one {@code .properties} * file, the last {@code @PropertySource} annotation processed will 'win' and override. * - * For example, given two properties files {@code a.properties} and + *

For example, given two properties files {@code a.properties} and * {@code b.properties}, consider the following two configuration classes * that reference them with {@code @PropertySource} annotations: * @@ -118,7 +123,7 @@ import org.springframework.core.io.support.PropertySourceFactory; * public class ConfigB { } * * - * The override ordering depends on the order in which these classes are registered + *

The override ordering depends on the order in which these classes are registered * with the application context. * * 

@@ -128,7 +133,7 @@ import org.springframework.core.io.support.PropertySourceFactory;
  * ctx.refresh();
  *
* - * In the scenario above, the properties in {@code b.properties} will override any + *

In the scenario above, the properties in {@code b.properties} will override any * duplicates that exist in {@code a.properties}, because {@code ConfigB} was registered * last. * @@ -150,6 +155,7 @@ import org.springframework.core.io.support.PropertySourceFactory; * @author Chris Beams * @author Juergen Hoeller * @author Phillip Webb + * @author Sam Brannen * @since 3.1 * @see PropertySources * @see Configuration diff --git a/spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java b/spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java index 34c2dd82277..f29024378de 100644 --- a/spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java +++ b/spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java @@ -40,11 +40,11 @@ import org.springframework.util.StringValueResolver; * within bean definition property values and {@code @Value} annotations against the current * Spring {@link Environment} and its set of {@link PropertySources}. * - *

This class is designed as a general replacement for {@code PropertyPlaceholderConfigurer} - * introduced in Spring 3.1. It is used by default to support the {@code property-placeholder} - * element in working against the spring-context-3.1 or higher XSD, whereas spring-context - * versions <= 3.0 default to {@code PropertyPlaceholderConfigurer} to ensure backward - * compatibility. See the spring-context XSD documentation for complete details. + *

This class is designed as a general replacement for {@code PropertyPlaceholderConfigurer}. + * It is used by default to support the {@code property-placeholder} element in working against + * the spring-context-3.1 or higher XSD; whereas, spring-context versions <= 3.0 default to + * {@code PropertyPlaceholderConfigurer} to ensure backward compatibility. See the spring-context + * XSD documentation for complete details. * *

Any local properties (e.g. those added via {@link #setProperties}, {@link #setLocations} * et al.) are added as a {@code PropertySource}. Search precedence of local properties is