org.springframework.scheduling.annotation.EnableAsync Maven / Gradle / Ivy
Show all versions of spring-context Show documentation
/*
* Copyright 2002-2015 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.scheduling.annotation;
import java.lang.annotation.Annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.context.annotation.AdviceMode;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
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:
*
*
* @Configuration
* @EnableAsync
* public class AppConfig {
* @Bean
* public MyAsyncBean asyncBean() {
* return new MyAsyncBean();
* }
* }
*
* 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
* {@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.
*
*
By default, a {@link org.springframework.core.task.SimpleAsyncTaskExecutor
* SimpleAsyncTaskExecutor} will be used to process async method invocations. Besides,
* annotated methods having a {@code void} return type cannot transmit any exception
* back to the caller. By default, such uncaught exceptions are only logged.
*
*
To customize all this, implement {@link AsyncConfigurer} and
* provide:
*
* - your own {@link java.util.concurrent.Executor Executor} through the
* {@link AsyncConfigurer#getAsyncExecutor() getAsyncExecutor()} method, and
* - your own {@link org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler
* AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler()
* 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, {@code null} can be returned to
* keep the default settings. Consider also extending from {@link AsyncConfigurerSupport}
* when possible.
*
*
For reference, the example above can be compared to the following Spring XML
* configuration:
*
* {@code
*
*
* }
* 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.
*
* @author Chris Beams
* @author Stephane Nicoll
* @since 3.1
* @see Async
* @see AsyncConfigurer
* @see AsyncConfigurationSelector
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(AsyncConfigurationSelector.class)
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.
*/
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}.
*
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.
*/
boolean proxyTargetClass() default false;
/**
* 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
* after all other post-processors, so that it can add an advisor to
* existing proxies rather than double-proxy.
*/
int order() default Ordered.LOWEST_PRECEDENCE;
}