程序包 cn.taketoday.scheduling.annotation

Annotation Interface EnableAsync

@Target(TYPE) @Retention(RUNTIME) @Documented public @interface EnableAsync
Enables asynchronous method execution capability, similar to functionality found in <task:*> XML namespace.

To be used together with @Configuration classes as follows, enabling annotation-driven async processing for an entire Framework application context: 

 @Configuration
 @EnableAsync
 public class AppConfig {

 }
MyAsyncBean is a user-defined type with one or more methods annotated with either @Async annotation, the EJB 3.1 @jakarta.ejb.Asynchronous annotation, or any custom annotation specified via the annotation() attribute. The aspect is added transparently for any registered bean, for instance via this configuration: 
 @Configuration
 public class AnotherAppConfig {

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

By default, Framework will be searching for an associated thread pool definition: either a unique TaskExecutor bean in the context, or an Executor bean named "taskExecutor" otherwise. If neither of the two is resolvable, 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:

NOTE: AsyncConfigurer configuration classes get initialized early in the application context bootstrap. If you need any dependencies on other beans there, make sure to declare them 'lazy' as far as possible in order to let them go through other post-processors as well. 

 @Configuration
 @EnableAsync
 public class AppConfig implements AsyncConfigurer {

     @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 new MyAsyncUncaughtExceptionHandler();
     }
 }

If only one item needs to be customized, null can be returned to keep the default settings.

Note: In the above example the ThreadPoolTaskExecutor is not a fully managed Framework bean. Add the @Component 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.

For reference, the example above can be compared to the following Framework 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 above XML-based and JavaConfig-based examples are equivalent except for the setting of the thread name prefix of the Executor; this is because the <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.

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. Please note that proxy mode allows for interception of calls through the proxy only; local calls within the same class cannot get intercepted that way.

Note that if the mode() is set to AdviceMode.ASPECTJ, then the value of the proxyTargetClass() attribute will be ignored. Note also that in this case the Framework-aspects module JAR must be present on the classpath, with compile-time weaving or load-time weaving applying the aspect to the affected classes. There is no proxy involved in such a scenario; local calls will be intercepted as well.

从以下版本开始:
4.0
作者:
Chris Beams, Juergen Hoeller, Stephane Nicoll, Sam Brannen
另请参阅:

  • 可选元素概要

    可选元素
    修饰符和类型
    可选元素
    说明
    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.

  • 元素详细资料

    • annotation

      Class<? extends Annotation> annotation
      Indicate the 'async' annotation type to be detected at either class or method level.

      By default, both @Async annotation and the EJB 3.1 @jakarta.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.

      默认值:
      java.lang.annotation.Annotation.class

    • proxyTargetClass

      boolean proxyTargetClass
      Indicate whether subclass-based (CGLIB) proxies are to be created as opposed to standard Java interface-based proxies.

      Applicable only if the mode() is set to AdviceMode.PROXY.

      The default is false.

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

      默认值:
      false

    • mode

      AdviceMode mode
      Indicate how async advice should be applied.

      The default is AdviceMode.PROXY. Please note that proxy mode allows for interception of calls through the proxy only. Local calls within the same class cannot get intercepted that way; an Async annotation on such a method within a local call will be ignored since interceptor does not even kick in for such a runtime scenario. For a more advanced mode of interception, consider switching this to AdviceMode.ASPECTJ.

      默认值:
      PROXY

    • order

      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.

      默认值:
      2147483647