org.springframework.scheduling.annotation

Annotation Type EnableAsync

@Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Documented
 @Import(value=AsyncConfigurationSelector.class)
public @interface EnableAsync

Enables Spring's asynchronous method execution capability, similar to functionality found in Spring's <task:*> XML namespace. To be used on @Configuration classes as follows:

 @Configuration
 @EnableAsync
 public class AppConfig {
     @Bean
     public MyAsyncBean asyncBean() {
         return new MyAsyncBean();
     }
 }

where MyAsyncBean is a user-defined type with one or methods annotated with @Async (or any custom annotation specified by the annotation() attribute).

The mode() attribute controls how advice is applied; if the mode is AdviceMode.PROXY (the default), then the other attributes control the behavior of the proxying.

Note that if the mode() is set to AdviceMode.ASPECTJ, then the proxyTargetClass() attribute is obsolete. Note also that in this case the spring-aspects module JAR must be present on the classpath.

By default, a SimpleAsyncTaskExecutor will be used to process async method invocations. Besides, annotated methods having a void return type cannot transmit any exception back to the caller. By default, such uncaught exceptions are only logged.

To customize all this, implement AsyncConfigurer and provide:

• your own Executor through the getAsyncExecutor() method, and
• your own AsyncUncaughtExceptionHandler through the getAsyncUncaughtExceptionHandler() method.

 @Configuration
 @EnableAsync
 public class AppConfig implements AsyncConfigurer {

     @Bean
     public MyAsyncBean asyncBean() {
         return new MyAsyncBean();
     }

     @Override
     public Executor getAsyncExecutor() {
         ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
         executor.setCorePoolSize(7);
         executor.setMaxPoolSize(42);
         executor.setQueueCapacity(11);
         executor.setThreadNamePrefix("MyExecutor-");
         executor.initialize();
         return executor;
     }

     @Override
     public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
         return MyAsyncUncaughtExceptionHandler();
     }
 }

If only one item needs to be customized, null can be returned to keep the default settings. Consider also extending from AsyncConfigurerSupport when possible.

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

 <beans>
     <task:annotation-driven executor="myExecutor" exception-handler="exceptionHandler"/>
     <task:executor id="myExecutor" pool-size="7-42" queue-capacity="11"/>
     <bean id="asyncBean" class="com.foo.MyAsyncBean"/>
     <bean id="exceptionHandler" class="com.foo.MyAsyncUncaughtExceptionHandler"/>
 </beans>
 

the examples are equivalent except the setting of the thread name prefix of the Executor; this is because the the task: namespace 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 ThreadPoolTaskExecutor is not a fully managed Spring Bean. Add the @Bean annotation to the getAsyncExecutor() method if you want a fully managed bean. In such circumstances it is no longer necessary to manually call the executor.initialize() method as this will be invoked automatically when the bean is initialized.

Since:

3.1

Author:

Chris Beams, Stephane Nicoll

See Also:

Async, AsyncConfigurer, AsyncConfigurationSelector

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.Class<? extends java.lang.annotation.Annotation>	annotation Indicate the 'async' annotation type to be detected at either class or method level.
AdviceMode	mode Indicate how async advice should be applied.
int	order Indicate the order in which the AsyncAnnotationBeanPostProcessor should be applied.
boolean	proxyTargetClass Indicate whether subclass-based (CGLIB) proxies are to be created as opposed to standard Java interface-based proxies.

Element Detail

annotation

public abstract java.lang.Class<? extends java.lang.annotation.Annotation> annotation

Indicate the 'async' annotation type to be detected at either class or method level. By default, both the Async annotation and the EJB 3.1 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.

Default:

java.lang.annotation.Annotation.class

proxyTargetClass

public abstract boolean proxyTargetClass

Indicate whether subclass-based (CGLIB) proxies are to be created as opposed to standard Java interface-based proxies. The default is false. Applicable only if mode() is set to AdviceMode.PROXY.

Note that setting this attribute to true will affect all Spring-managed beans requiring proxying, not just those marked with @Async. For example, other beans marked with Spring's @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.

Default:

false

mode

public abstract AdviceMode mode

Indicate how async advice should be applied. The default is AdviceMode.PROXY.

See Also:

AdviceMode

Default:

org.springframework.context.annotation.AdviceMode.PROXY

order

public abstract int order

Indicate the order in which the AsyncAnnotationBeanPostProcessor should be applied. The default is 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.

Default:

2147483647