EnableAsync (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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. To customize this behavior, implement `AsyncConfigurer` and provide your own `Executor` through the `getExecutor()` 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;
           }
       }

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

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

  the examples are equivalent save 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
  See Also:
    `Async`, `AsyncConfigurer`, `AsyncConfigurationSelector`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `Class<? extends 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 Class<? extends 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