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

Polish Javadoc for @EnableAsync

This commit is contained in:
Sam Brannen 2015-09-02 19:08:56 +02:00
parent ec741bd5ea
commit 93f3b9cbe0
1 changed files with 40 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java
View File

@ -30,8 +30,12 @@ import org.springframework.core.Ordered;
/**
* Enables Spring's asynchronous method execution capability, similar to functionality
* found in Spring's {@code <task:*>} XML namespace. To be used on @{@link Configuration}
* classes as follows:
* found in Spring's {@code <task:*>} XML namespace.
*
* <p>To be used on @{@link Configuration} classes as follows, where {@code MyAsyncBean}
* is a user-defined type with one or more methods annotated with either Spring's
* {@code @Async} annotation, the EJB 3.1 {@code @javax.ejb.Asynchronous} annotation,
* or any custom annotation specified via the {@link #annotation} attribute.
*
* <pre class="code">
* &#064;Configuration
@ -43,17 +47,15 @@ import org.springframework.core.Ordered;
* }
* }</pre>
*
* where {@code MyAsyncBean} is a user-defined type with one or methods annotated
* with @{@link Async} (or any custom annotation specified by the {@link #annotation()}
* attribute).
*
* <p>The {@link #mode()} attribute controls how advice is applied; if the mode is
* <p>The {@link #mode} attribute controls how advice is applied; if the mode is
* {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
* of the proxying.
*
* <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then
* the {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the
* {@code spring-aspects} module JAR must be present on the classpath.
* the value of the {@link #proxyTargetClass} attribute will be ignored. Note also
* that in this case the {@code spring-aspects} module JAR must be present on the
* classpath.
*
* <p>By default, a {@link org.springframework.core.task.SimpleAsyncTaskExecutor
* SimpleAsyncTaskExecutor} will be used to process async method invocations. Besides,
@ -64,9 +66,9 @@ import org.springframework.core.Ordered;
* provide:
* <ul>
* <li>your own {@link java.util.concurrent.Executor Executor} through the
* {@link AsyncConfigurer#getAsyncExecutor() getAsyncExecutor()} method, and</li>
* {@link AsyncConfigurer#getAsyncExecutor getAsyncExecutor()} method, and</li>
* <li>your own {@link org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler
* AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler()
* AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler
* getAsyncUncaughtExceptionHandler()}
* method.</li>
* </ul>
@ -102,6 +104,12 @@ import org.springframework.core.Ordered;
* keep the default settings. Consider also extending from {@link AsyncConfigurerSupport}
* when possible.
*
* <p>Note: In the above example the {@code ThreadPoolTaskExecutor} is not a fully managed
* Spring bean. Add the {@code @Bean} annotation to the {@code getAsyncExecutor()} method
* if you want a fully managed bean. In such circumstances it is no longer necessary to
* manually call the {@code executor.initialize()} method as this will be invoked
* automatically when the bean is initialized.
*
* <p>For reference, the example above can be compared to the following Spring XML
* configuration:
* <pre class="code">
@ -113,19 +121,16 @@ import org.springframework.core.Ordered;
* <bean id="exceptionHandler" class="com.foo.MyAsyncUncaughtExceptionHandler"/>
* </beans>
* }</pre>
* the examples are equivalent except the setting of the <em>thread name prefix</em> of the
* Executor; this is because the the {@code task:} namespace {@code executor} element does
* not expose such an attribute. This demonstrates how the code-based approach allows for
* maximum configurability through direct access to actual componentry.
*
* <p>Note: In the above example the {@code ThreadPoolTaskExecutor} is not a fully managed
* Spring Bean. Add the {@code @Bean} annotation to the {@code getAsyncExecutor()} method
* if you want a fully managed bean. In such circumstances it is no longer necessary to
* manually call the {@code executor.initialize()} method as this will be invoked
* automatically when the bean is initialized.
* The above XML-based and JavaConfig-based examples are equivalent except for the
* setting of the <em>thread name prefix</em> of the {@code Executor}; this is because
* the {@code <task:executor>} element does not expose such an attribute. This
* demonstrates how the JavaConfig-based approach allows for maximum configurability
* through direct access to actual componentry.
*
* @author Chris Beams
* @author Stephane Nicoll
* @author Sam Brannen
* @since 3.1
* @see Async
* @see AsyncConfigurer
@ -138,39 +143,42 @@ import org.springframework.core.Ordered;
public @interface EnableAsync {
/**
* Indicate the 'async' annotation type to be detected at either class or
* method level. By default, both the {@link Async} annotation and the
* EJB 3.1 {@code javax.ejb.Asynchronous} annotation will be detected.
* <p>This setter property exists so that developers can provide their
* own (non-Spring-specific) annotation type to indicate that a method
* (or all methods of a given class) should be invoked asynchronously.
* Indicate the 'async' annotation type to be detected at either class
* or method level.
* <p>By default, both Spring's @{@link Async} annotation and the EJB
* 3.1 {@code @javax.ejb.Asynchronous} annotation will be detected.
* <p>This attribute exists so that developers can provide their own
* custom annotation type to indicate that a method (or all methods of
* a given class) should be invoked asynchronously.
*/
Class<? extends Annotation> annotation() default Annotation.class;
/**
* Indicate whether subclass-based (CGLIB) proxies are to be created as opposed
* to standard Java interface-based proxies. The default is {@code false}. <strong>
* Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}</strong>.
* to standard Java interface-based proxies.
* <p><strong>Applicable only if the {@link #mode} is set to {@link AdviceMode#PROXY}</strong>.
* <p>The default is {@code false}.
* <p>Note that setting this attribute to {@code true} will affect <em>all</em>
* Spring-managed beans requiring proxying, not just those marked with {@code @Async}.
* For example, other beans marked with Spring's {@code @Transactional} annotation
* will be upgraded to subclass proxying at the same time. This approach has no
* negative impact in practice unless one is explicitly expecting one type of proxy
* vs another, e.g. in tests.
* vs. another &mdash; for example, in tests.
*/
boolean proxyTargetClass() default false;
/**
* Indicate how async advice should be applied. The default is
* {@link AdviceMode#PROXY}.
* Indicate how async advice should be applied.
* <p>The default is {@link AdviceMode#PROXY}.
* @see AdviceMode
*/
AdviceMode mode() default AdviceMode.PROXY;
/**
* Indicate the order in which the
* {@link org.springframework.scheduling.annotation.AsyncAnnotationBeanPostProcessor}
* should be applied. The default is {@link Ordered#LOWEST_PRECEDENCE} in order to run
* {@link org.springframework.scheduling.annotation.AsyncAnnotationBeanPostProcessor
* AsyncAnnotationBeanPostProcessor} should be applied.
* <p>The default is {@link Ordered#LOWEST_PRECEDENCE} in order to run
* after all other post-processors, so that it can add an advisor to
* existing proxies rather than double-proxy.
*/