From 93f3b9cbe08e3eb7f29c4cff1f66c439484a7f8e Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Wed, 2 Sep 2015 19:08:56 +0200 Subject: [PATCH] Polish Javadoc for @EnableAsync --- .../scheduling/annotation/EnableAsync.java | 72 ++++++++++--------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java b/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java index 9c9f439732..ad7c3b0416 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java +++ b/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java @@ -30,8 +30,12 @@ import org.springframework.core.Ordered; /** * Enables Spring's asynchronous method execution capability, similar to functionality - * found in Spring's {@code } XML namespace. To be used on @{@link Configuration} - * classes as follows: + * found in Spring's {@code } XML namespace. + * + *

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. * * 

  * @Configuration
@@ -43,17 +47,15 @@ import org.springframework.core.Ordered;
  *     }
  * }
* - * 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). * - *

The {@link #mode()} attribute controls how advice is applied; if the mode is + *

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. * *

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. * *

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: *

    *
  • your own {@link java.util.concurrent.Executor Executor} through the - * {@link AsyncConfigurer#getAsyncExecutor() getAsyncExecutor()} method, and
    • + * {@link AsyncConfigurer#getAsyncExecutor getAsyncExecutor()} method, and *
  • your own {@link org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler - * AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler() + * AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler * getAsyncUncaughtExceptionHandler()} * method.
    • *
@@ -102,6 +104,12 @@ import org.springframework.core.Ordered; * keep the default settings. Consider also extending from {@link AsyncConfigurerSupport} * when possible. * + *

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. + * *

For reference, the example above can be compared to the following Spring XML * configuration: * 

@@ -113,19 +121,16 @@ import org.springframework.core.Ordered;
  *     
  * 
  * }
- * the examples are equivalent except the setting of the thread name prefix 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. * - *

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 thread name prefix of the {@code Executor}; this is because + * the {@code } 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. - *

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. + *

By default, both Spring's @{@link Async} annotation and the EJB + * 3.1 {@code @javax.ejb.Asynchronous} annotation will be detected. + *

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 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}. - * Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}. + * to standard Java interface-based proxies. + *

Applicable only if the {@link #mode} is set to {@link AdviceMode#PROXY}. + *

The default is {@code false}. *

Note that setting this attribute to {@code true} will affect all * 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 — 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. + *

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. + *

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. */