How Spring Enables Asynchronous Execution with @EnableAsync – Deep Dive

In modern project development, asynchronous execution is a common choice to improve performance, and Spring provides built‑in support via the @EnableAsync and @Async annotations. This article analyses the source code behind Spring's async support.

@EnableAsync enables async support

The @EnableAsync annotation follows the same enable* pattern as @EnableAspectJAutoProxy or @EnableTransactionManagement. Its source declares several attributes that control the async behavior, such as annotation(), proxyTargetClass(), mode(), and order().

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(AsyncConfigurationSelector.class)
public @interface EnableAsync {
    Class<? extends Annotation> annotation() default Annotation.class;
    boolean proxyTargetClass() default false;
    AdviceMode mode() default AdviceMode.PROXY;
    int order() default Ordered.LOWEST_PRECEDENCE;
}

These attributes are similar to those used in Spring's declarative transaction support.

AsyncConfigurationSelector selects the configuration class

AsyncConfigurationSelector

implements AdviceModeImportSelector and imports different configuration classes based on the mode attribute of @EnableAsync. When mode = PROXY, it imports ProxyAsyncConfiguration.

public class AsyncConfigurationSelector extends AdviceModeImportSelector<EnableAsync> {
    @Override
    public String[] selectImports(AdviceMode adviceMode) {
        switch (adviceMode) {
            case PROXY: return new String[] { ProxyAsyncConfiguration.class.getName() };
            case ASPECTJ: return new String[] { ASYNC_EXECUTION_ASPECT_CONFIGURATION_CLASS_NAME };
            default: return null;
        }
    }
}

ProxyAsyncConfiguration creates the async bean post‑processor

The imported ProxyAsyncConfiguration extends AbstractAsyncConfiguration and defines a @Bean method that returns an AsyncAnnotationBeanPostProcessor instance.

@Configuration
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public class ProxyAsyncConfiguration extends AbstractAsyncConfiguration {
    @Bean(name = TaskManagementConfigUtils.ASYNC_ANNOTATION_PROCESSOR_BEAN_NAME)
    @Role(BeanDefinition.ROLE_INFRASTRUCTURE)
    public AsyncAnnotationBeanPostProcessor asyncAdvisor() {
        Assert.notNull(this.enableAsync, "@EnableAsync annotation metadata was not injected");
        AsyncAnnotationBeanPostProcessor bpp = new AsyncAnnotationBeanPostProcessor();
        Class<? extends Annotation> customAsyncAnnotation = this.enableAsync.getClass("annotation");
        if (customAsyncAnnotation != AnnotationUtils.getDefaultValue(EnableAsync.class, "annotation")) {
            bpp.setAsyncAnnotationType(customAsyncAnnotation);
        }
        if (this.executor != null) {
            bpp.setExecutor(this.executor);
        }
        if (this.exceptionHandler != null) {
            bpp.setExceptionHandler(this.exceptionHandler);
        }
        bpp.setProxyTargetClass(this.enableAsync.getBoolean("proxyTargetClass"));
        bpp.setOrder(this.enableAsync.<Integer>getNumber("order"));
        return bpp;
    }
}

AbstractAsyncConfiguration parses @EnableAsync metadata

The abstract base class stores the annotation attributes and autowires any AsyncConfigurer beans to obtain a custom executor or exception handler.

@Configuration
public abstract class AbstractAsyncConfiguration implements ImportAware {
    protected AnnotationAttributes enableAsync;
    protected Executor executor;
    protected AsyncUncaughtExceptionHandler exceptionHandler;

    @Override
    public void setImportMetadata(AnnotationMetadata importMetadata) {
        this.enableAsync = AnnotationAttributes.fromMap(
            importMetadata.getAnnotationAttributes(EnableAsync.class.getName(), false));
        if (this.enableAsync == null) {
            throw new IllegalArgumentException("@EnableAsync is not present on importing class " + importMetadata.getClassName());
        }
    }

    @Autowired(required = false)
    void setConfigurers(Collection<AsyncConfigurer> configurers) {
        if (CollectionUtils.isEmpty(configurers)) return;
        if (configurers.size() > 1) {
            throw new IllegalStateException("Only one AsyncConfigurer may exist");
        }
        AsyncConfigurer configurer = configurers.iterator().next();
        this.executor = configurer.getAsyncExecutor();
        this.exceptionHandler = configurer.getAsyncUncaughtExceptionHandler();
    }
}

AsyncAnnotationBeanPostProcessor builds the async advisor

The post‑processor implements BeanFactoryAware and creates an AsyncAnnotationAdvisor that holds the advice and pointcut for async interception.

@Override
public void setBeanFactory(BeanFactory beanFactory) {
    super.setBeanFactory(beanFactory);
    AsyncAnnotationAdvisor advisor = new AsyncAnnotationAdvisor(this.executor, this.exceptionHandler);
    if (this.asyncAnnotationType != null) {
        advisor.setAsyncAnnotationType(this.asyncAnnotationType);
    }
    advisor.setBeanFactory(beanFactory);
    this.advisor = advisor;
}

Advisor builds advice and pointcut

The advisor constructs an AnnotationAsyncExecutionInterceptor as advice and a composite pointcut that matches both class‑level and method‑level async annotations.

protected Advice buildAdvice(Executor executor, AsyncUncaughtExceptionHandler exceptionHandler) {
    return new AnnotationAsyncExecutionInterceptor(executor, exceptionHandler);
}

protected Pointcut buildPointcut(Set<Class<? extends Annotation>> asyncAnnotationTypes) {
    ComposablePointcut result = null;
    for (Class<? extends Annotation> asyncAnnotationType : asyncAnnotationTypes) {
        Pointcut cpc = new AnnotationMatchingPointcut(asyncAnnotationType, true);
        Pointcut mpc = AnnotationMatchingPointcut.forMethodAnnotation(asyncAnnotationType);
        if (result == null) {
            result = new ComposablePointcut(cpc);
        } else {
            result.union(cpc);
        }
        result = result.union(mpc);
    }
    return result;
}

AnnotationAsyncExecutionInterceptor performs the method interception

The interceptor extracts the target method, determines the appropriate AsyncTaskExecutor, wraps the method call in a Callable, and submits it for asynchronous execution.

public Object invoke(final MethodInvocation invocation) throws Throwable {
    Class<?> targetClass = (invocation.getThis() != null ? AopUtils.getTargetClass(invocation.getThis()) : null);
    Method specificMethod = ClassUtils.getMostSpecificMethod(invocation.getMethod(), targetClass);
    final Method userDeclaredMethod = BridgeMethodResolver.findBridgedMethod(specificMethod);
    AsyncTaskExecutor executor = determineAsyncExecutor(userDeclaredMethod);
    if (executor == null) {
        throw new IllegalStateException("No executor specified and no default executor set on AsyncExecutionInterceptor either");
    }
    Callable<Object> task = new Callable<Object>() {
        @Override
        public Object call() throws Exception {
            try {
                Object result = invocation.proceed();
                if (result instanceof Future) {
                    return ((Future<?>) result).get();
                }
            } catch (ExecutionException ex) {
                handleError(ex.getCause(), userDeclaredMethod, invocation.getArguments());
            } catch (Throwable ex) {
                handleError(ex, userDeclaredMethod, invocation.getArguments());
            }
            return null;
        }
    };
    return doSubmit(task, executor, invocation.getMethod().getReturnType());
}

The determineAsyncExecutor method looks for a qualified executor bean, falls back to a default executor, and finally creates a SimpleAsyncTaskExecutor if none is found.

protected AsyncTaskExecutor determineAsyncExecutor(Method method) {
    AsyncTaskExecutor executor = this.executors.get(method);
    if (executor == null) {
        Executor targetExecutor;
        String qualifier = getExecutorQualifier(method);
        if (StringUtils.hasLength(qualifier)) {
            targetExecutor = findQualifiedExecutor(this.beanFactory, qualifier);
        } else {
            targetExecutor = this.defaultExecutor;
            if (targetExecutor == null) {
                synchronized (this.executors) {
                    if (this.defaultExecutor == null) {
                        this.defaultExecutor = getDefaultExecutor(this.beanFactory);
                    }
                    targetExecutor = this.defaultExecutor;
                }
            }
        }
        if (targetExecutor == null) {
            return null;
        }
        executor = (targetExecutor instanceof AsyncListenableTaskExecutor) ?
                (AsyncListenableTaskExecutor) targetExecutor : new TaskExecutorAdapter(targetExecutor);
        this.executors.put(method, executor);
    }
    return executor;
}

Finally, doSubmit delegates the task to the chosen executor, handling return types such as Future or ListenableFuture.

protected Object doSubmit(Callable<Object> task, AsyncTaskExecutor executor, Class<?> returnType) {
    if (completableFuturePresent) {
        Future<Object> result = CompletableFutureDelegate.processCompletableFuture(returnType, task, executor);
        if (result != null) {
            return result;
        }
    }
    if (ListenableFuture.class.isAssignableFrom(returnType)) {
        return ((AsyncListenableTaskExecutor) executor).submitListenable(task);
    } else if (Future.class.isAssignableFrom(returnType)) {
        return executor.submit(task);
    } else {
        executor.submit(task);
        return null;
    }
}

Through this chain of configuration classes, selectors, and post‑processors, Spring automatically creates proxies for beans that contain @Async methods, allowing those methods to run in separate threads without the developer writing any threading code.

—

Source: CSDN Blog