Document default embedded value resolver support for property

placeholders

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

spring-context/src/main/java/org/springframework/context/annotation/Configuration.java

@@ -162,8 +162,8 @@ import org.springframework.stereotype.Component;
  *
  * <h3>Using the {@code @Value} annotation</h3>
  *
- * <p>Externalized values may be injected {@code @Configuration} classes using the
+ * <p>Externalized values may be injected into {@code @Configuration} classes using
- * {@link Value @Value} annotation:
+ * the {@link Value @Value} annotation:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -178,13 +178,23 @@ import org.springframework.stereotype.Component;
  *     }
  * }</pre>
  *
- * <p>This approach is most useful when using Spring's
+ * <p>This approach is often used in conjunction with Spring's
  * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
- * PropertySourcesPlaceholderConfigurer}, usually enabled via XML with
+ * PropertySourcesPlaceholderConfigurer} that can be enabled <em>automatically</em>
- * {@code <context:property-placeholder/>}.  See the section below on composing
+ * in XML configuration via {@code <context:property-placeholder/>} or <em>explicitly</em>
- * {@code @Configuration} classes with Spring XML using {@code @ImportResource},
+ * in a {@code @Configuration} class via a dedicated {@code static} {@code @Bean} method
- * see the {@link Value @Value} javadocs, and see the {@link Bean @Bean} javadocs for
+ * (see "a note on BeanFactoryPostProcessor-returning {@code @Bean} methods" of
- * details on working with {@code BeanFactoryPostProcessor} types such as
+ * {@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 <em>embedded value
+ * resolver</em> for the {@code ApplicationContext}, Spring will register a default
+ * <em>embedded value resolver</em> 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}.
  *
  * <h2>Composing {@code @Configuration} classes</h2>

spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java

@@ -54,25 +54,30 @@ import org.springframework.core.io.support.PropertySourceFactory;
  *     }
  * }</pre>
  *
- * Notice that the {@code Environment} object is
+ * <p>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".
  *
- * <h3>Resolving ${...} placeholders in {@code <bean>} and {@code @Value} annotations</h3>
+ * <h3>Resolving <code>${...}</code> placeholders in {@code <bean>} and {@code @Value} annotations</h3>
  *
- * In order to resolve ${...} placeholders in {@code <bean>} definitions or {@code @Value}
+ * <p>In order to resolve ${...} placeholders in {@code <bean>} definitions or {@code @Value}
- * annotations using properties from a {@code PropertySource}, one must register
+ * annotations using properties from a {@code PropertySource}, you must ensure that an
- * a {@code PropertySourcesPlaceholderConfigurer}. This happens automatically when using
+ * appropriate <em>embedded value resolver</em> is registered in the {@code BeanFactory}
- * {@code <context:property-placeholder>} in XML, but must be explicitly registered using
+ * used by the {@code ApplicationContext}. This happens automatically when using
- * a {@code static} {@code @Bean} method when using {@code @Configuration} classes. See
+ * {@code <context:property-placeholder>} in XML. When using {@code @Configuration} classes
- * the "Working with externalized values" section of @{@link Configuration}'s javadoc and
+ * this can be achieved by explicitly registering a {@code PropertySourcesPlaceholderConfigurer}
- * "a note on BeanFactoryPostProcessor-returning @Bean methods" of @{@link Bean}'s javadoc
+ * via a {@code static} {@code @Bean} method. Note, however, that explicit registration
- * for details and examples.
+ * 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.
  *
  * <h3>Resolving ${...} placeholders within {@code @PropertySource} resource locations</h3>
  *
- * Any ${...} placeholders present in a {@code @PropertySource} {@linkplain #value()
+ * <p>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;
  *     }
  * }</pre>
  *
- * Assuming that "my.placeholder" is present in one of the property sources already
+ * <p>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;
  *
  * <h3>A note on property overriding with @PropertySource</h3>
  *
- * In cases where a given property key exists in more than one {@code .properties}
+ * <p>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
+ * <p>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 { }
  * </pre>
  *
- * The override ordering depends on the order in which these classes are registered
+ * <p>The override ordering depends on the order in which these classes are registered
  * with the application context.
  *
  * <pre class="code">
@@ -128,7 +133,7 @@ import org.springframework.core.io.support.PropertySourceFactory;
  * ctx.refresh();
  * </pre>
  *
- * In the scenario above, the properties in {@code b.properties} will override any
+ * <p>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

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