Polishing

2019-04-03 17:14:12 +02:00
parent e37715a45a
commit 601e352f8c
14 changed files with 273 additions and 222 deletions
--- a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java
+++ b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-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.
@@ -46,7 +46,7 @@ import org.springframework.stereotype.Component;
 *
 * <h3>Via {@code AnnotationConfigApplicationContext}</h3>
 *
- * {@code @Configuration} classes are typically bootstrapped using either
+ * <p>{@code @Configuration} classes are typically bootstrapped using either
 * {@link AnnotationConfigApplicationContext} or its web-capable variant,
 * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
 * AnnotationConfigWebApplicationContext}. A simple example with the former follows:
@@ -59,23 +59,25 @@ import org.springframework.stereotype.Component;
 * // use myBean ...
 * </pre>
 *
- * See {@link AnnotationConfigApplicationContext} Javadoc for further details and see
+ * <p>See the {@link AnnotationConfigApplicationContext} javadocs for further details, and see
 * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
- * AnnotationConfigWebApplicationContext} for {@code web.xml} configuration instructions.
+ * AnnotationConfigWebApplicationContext} for web configuration instructions in a
+ * {@code Servlet} container.
 *
 * <h3>Via Spring {@code <beans>} XML</h3>
 *
 * <p>As an alternative to registering {@code @Configuration} classes directly against an
 * {@code AnnotationConfigApplicationContext}, {@code @Configuration} classes may be
 * declared as normal {@code <bean>} definitions within Spring XML files:
- * <pre class="code">
- * {@code
- * <beans>
- *    <context:annotation-config/>
- *    <bean class="com.acme.AppConfig"/>
- * </beans>}</pre>
 *
- * In the example above, {@code <context:annotation-config/>} is required in order to
+ * <pre class="code">
+ * &lt;beans&gt;
+ *    &lt;context:annotation-config/&gt;
+ *    &lt;bean class="com.acme.AppConfig"/&gt;
+ * &lt;/beans&gt;
+ * </pre>
+ *
+ * <p>In the example above, {@code <context:annotation-config/>} is required in order to
 * enable {@link ConfigurationClassPostProcessor} and other annotation-related
 * post processors that facilitate handling {@code @Configuration} classes.
 *
@@ -86,11 +88,12 @@ import org.springframework.stereotype.Component;
 * Spring XML's {@code <context:component-scan/>} element) and therefore may also take
 * advantage of {@link Autowired @Autowired}/{@link javax.inject.Inject @Inject}
 * like any regular {@code @Component}. In particular, if a single constructor is present
- * autowiring semantics will be applied transparently:
+ * autowiring semantics will be applied transparently for that constructor:
 *
 * <pre class="code">
 * &#064;Configuration
 * public class AppConfig {
+ *
 *     private final SomeBean someBean;
 *
 *     public AppConfig(SomeBean someBean) {
@@ -112,15 +115,15 @@ import org.springframework.stereotype.Component;
 *     // various &#064;Bean definitions ...
 * }</pre>
 *
- * See the {@link ComponentScan @ComponentScan} javadoc for details.
+ * <p>See the {@link ComponentScan @ComponentScan} javadocs for details.
 *
 * <h2>Working with externalized values</h2>
 *
 * <h3>Using the {@code Environment} API</h3>
 *
- * Externalized values may be looked up by injecting the Spring
+ * <p>Externalized values may be looked up by injecting the Spring
 * {@link org.springframework.core.env.Environment} into a {@code @Configuration}
- * class as usual (e.g. using the {@code @Autowired} annotation):
+ * class &mdash; for example, using the {@code @Autowired} annotation:
 *
 * <pre class="code">
 * &#064;Configuration
@@ -136,7 +139,7 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * Properties resolved through the {@code Environment} reside in one or more "property
+ * <p>Properties resolved through the {@code Environment} reside in one or more "property
 * source" objects, and {@code @Configuration} classes may contribute property sources to
 * the {@code Environment} object using the {@link PropertySource @PropertySource}
 * annotation:
@@ -154,12 +157,12 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * See {@link org.springframework.core.env.Environment Environment}
- * and {@link PropertySource @PropertySource} Javadoc for further details.
+ * <p>See the {@link org.springframework.core.env.Environment Environment}
+ * and {@link PropertySource @PropertySource} javadocs for further details.
 *
 * <h3>Using the {@code @Value} annotation</h3>
 *
- * Externalized values may be 'wired into' {@code @Configuration} classes using
+ * <p>Externalized values may be injected into {@code @Configuration} classes using
 * the {@link Value @Value} annotation:
 *
 * <pre class="code">
@@ -175,13 +178,23 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * 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
- * {@code <context:property-placeholder/>}.  See the section below on composing
- * {@code @Configuration} classes with Spring XML using {@code @ImportResource},
- * see {@link Value @Value} Javadoc, and see {@link Bean @Bean} Javadoc for details on working with
- * {@code BeanFactoryPostProcessor} types such as
+ * PropertySourcesPlaceholderConfigurer} that can be enabled <em>automatically</em>
+ * in XML configuration via {@code <context:property-placeholder/>} or <em>explicitly</em>
+ * 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 <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>
@@ -189,9 +202,9 @@ import org.springframework.stereotype.Component;
 * <h3>With the {@code @Import} annotation</h3>
 *
 * <p>{@code @Configuration} classes may be composed using the {@link Import @Import} annotation,
- * not unlike the way that {@code <import>} works in Spring XML. Because
+ * similar to the way that {@code <import>} works in Spring XML. Because
 * {@code @Configuration} objects are managed as Spring beans within the container,
- * imported configurations may be injected the usual way (e.g. via constructor injection):
+ * imported configurations may be injected &mdash; for example, via constructor injection:
 *
 * <pre class="code">
 * &#064;Configuration
@@ -220,7 +233,7 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped
+ * <p>Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped
 * by registering only {@code AppConfig} against the Spring context:
 *
 * <pre class="code">
@@ -228,7 +241,7 @@ import org.springframework.stereotype.Component;
 *
 * <h3>With the {@code @Profile} annotation</h3>
 *
- * {@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
+ * <p>{@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
 * indicate they should be processed only if a given profile or profiles are <em>active</em>:
 *
 * <pre class="code">
@@ -252,8 +265,8 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * Alternatively, you may also declare profile conditions at the {@code @Bean} method level,
- * e.g. for alternative bean variants within the same configuration class:
+ * <p>Alternatively, you may also declare profile conditions at the {@code @Bean} method level
+ * &mdash; for example, for alternative bean variants within the same configuration class:
 *
 * <pre class="code">
 * &#064;Configuration
@@ -268,16 +281,16 @@ import org.springframework.stereotype.Component;
 *     public DataSource productionDatabase() { ... }
 * }</pre>
 *
- * See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
+ * <p>See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
 * javadocs for further details.
 *
 * <h3>With Spring XML using the {@code @ImportResource} annotation</h3>
 *
- * As mentioned above, {@code @Configuration} classes may be declared as regular Spring
+ * <p>As mentioned above, {@code @Configuration} classes may be declared as regular Spring
 * {@code <bean>} definitions within Spring XML files. It is also possible to
 * import Spring XML configuration files into {@code @Configuration} classes using
 * the {@link ImportResource @ImportResource} annotation. Bean definitions imported from
- * XML can be injected the usual way (e.g. using the {@code Inject} annotation):
+ * XML can be injected &mdash; for example, using the {@code @Inject} annotation:
 *
 * <pre class="code">
 * &#064;Configuration
@@ -295,7 +308,7 @@ import org.springframework.stereotype.Component;
 *
 * <h3>With nested {@code @Configuration} classes</h3>
 *
- * {@code @Configuration} classes may be nested within one another as follows:
+ * <p>{@code @Configuration} classes may be nested within one another as follows:
 *
 * <pre class="code">
 * &#064;Configuration
@@ -317,11 +330,11 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * When bootstrapping such an arrangement, only {@code AppConfig} need be registered
+ * <p>When bootstrapping such an arrangement, only {@code AppConfig} need be registered
 * against the application context. By virtue of being a nested {@code @Configuration}
 * class, {@code DatabaseConfig} <em>will be registered automatically</em>. This avoids
 * the need to use an {@code @Import} annotation when the relationship between
- * {@code AppConfig} {@code DatabaseConfig} is already implicitly clear.
+ * {@code AppConfig} and {@code DatabaseConfig} is already implicitly clear.
 *
 * <p>Note also that nested {@code @Configuration} classes can be used to good effect
 * with the {@code @Profile} annotation to provide two options of the same bean to the
@@ -337,13 +350,13 @@ import org.springframework.stereotype.Component;
 *
 * <h2>Testing support for {@code @Configuration} classes</h2>
 *
- * The Spring <em>TestContext framework</em> available in the {@code spring-test} module
- * provides the {@code @ContextConfiguration} annotation, which as of Spring 3.1 can
- * accept an array of {@code @Configuration} {@code Class} objects:
+ * <p>The Spring <em>TestContext framework</em> available in the {@code spring-test} module
+ * provides the {@code @ContextConfiguration} annotation which can accept an array of
+ * {@code @Configuration} {@code Class} objects:
 *
 * <pre class="code">
- * &#064;RunWith(SpringJUnit4ClassRunner.class)
- * &#064;ContextConfiguration(classes={AppConfig.class, DatabaseConfig.class})
+ * &#064;RunWith(SpringRunner.class)
+ * &#064;ContextConfiguration(classes = {AppConfig.class, DatabaseConfig.class})
 * public class MyTests {
 *
 *     &#064;Autowired MyBean myBean;
@@ -356,14 +369,16 @@ import org.springframework.stereotype.Component;
 *     }
 * }</pre>
 *
- * See TestContext framework reference documentation for details.
+ * <p>See the
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html#testcontext-framework">TestContext framework</a>
+ * reference documentation for details.
 *
 * <h2>Enabling built-in Spring features using {@code @Enable} annotations</h2>
 *
- * Spring features such as asynchronous method execution, scheduled task execution,
+ * <p>Spring features such as asynchronous method execution, scheduled task execution,
 * annotation driven transaction management, and even Spring MVC can be enabled and
- * configured from {@code @Configuration}
- * classes using their respective "{@code @Enable}" annotations. See
+ * configured from {@code @Configuration} classes using their respective "{@code @Enable}"
+ * annotations. See
 * {@link org.springframework.scheduling.annotation.EnableAsync @EnableAsync},
 * {@link org.springframework.scheduling.annotation.EnableScheduling @EnableScheduling},
 * {@link org.springframework.transaction.annotation.EnableTransactionManagement @EnableTransactionManagement},
@@ -406,15 +421,16 @@ import org.springframework.stereotype.Component;
 public @interface Configuration {

 	/**
-	 * Explicitly specify the name of the Spring bean definition associated
-	 * with this Configuration class. If left unspecified (the common case),
-	 * a bean name will be automatically generated.
-	 * <p>The custom name applies only if the Configuration class is picked up via
-	 * component scanning or supplied directly to a {@link AnnotationConfigApplicationContext}.
-	 * If the Configuration class is registered as a traditional XML bean definition,
-	 * the name/id of the bean element will take precedence.
-	 * @return the suggested component name, if any (or empty String otherwise)
-	 * @see org.springframework.beans.factory.support.DefaultBeanNameGenerator
+	 * Explicitly specify the name of the Spring bean definition associated with the
+	 * {@code @Configuration} class. If left unspecified (the common case), a bean
+	 * name will be automatically generated.
+	 * <p>The custom name applies only if the {@code @Configuration} class is picked
+	 * up via component scanning or supplied directly to an
+	 * {@link AnnotationConfigApplicationContext}. If the {@code @Configuration} class
+	 * is registered as a traditional XML bean definition, the name/id of the bean
+	 * element will take precedence.
+	 * @return the explicit component name, if any (or empty String otherwise)
+	 * @see AnnotationBeanNameGenerator
 	 */
 	@AliasFor(annotation = Component.class)
 	String value() default "";