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