root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Polish JavaDoc for @Configuration

This commit is contained in:
Sam Brannen 2018-08-26 22:07:07 +02:00
parent 08ba53dd0e
commit 4883b8aa03
1 changed files with 38 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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,15 +59,17 @@ 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">
* &lt;beans&gt;
* &lt;context:annotation-config/&gt;
@ -75,7 +77,7 @@ import org.springframework.stereotype.Component;
* &lt;/beans&gt;
* </pre>
*
* In the example above, {@code <context:annotation-config/>} is required in order to
* <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.
*
@ -113,13 +115,13 @@ 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 &mdash; for example, using the {@code @Autowired} annotation:
*
@ -137,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:
@ -155,13 +157,13 @@ 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
* the {@link Value @Value} annotation:
* <p>Externalized values may be injected {@code @Configuration} classes using the
* {@link Value @Value} annotation:
*
* <pre class="code">
* &#064;Configuration
@ -176,13 +178,13 @@ import org.springframework.stereotype.Component;
* }
* }</pre>
*
* This approach is most useful when using Spring's
* <p>This approach is most useful when using 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
* 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>
@ -221,7 +223,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">
@ -229,7 +231,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">
@ -253,8 +255,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
@ -269,12 +271,12 @@ 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
@ -296,7 +298,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
@ -318,11 +320,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
@ -338,7 +340,7 @@ 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
* <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:
*
@ -363,10 +365,10 @@ import org.springframework.stereotype.Component;
*
* <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},
@ -409,14 +411,15 @@ 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)
* 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 org.springframework.beans.factory.support.DefaultBeanNameGenerator
*/
@AliasFor(annotation = Component.class)