By WebNest Studio Engineering Team
Spring Boot Tutorial
Async Processing with @Async
Some work should not make the user wait: sending a welcome email, generating a PDF, resizing an uploaded image, calling a slow partner API whose result is not needed for the response. Running such work on another thread keeps requests fast.
Spring's @Async annotation runs a method on a background thread pool with a single line of code. This lesson covers enabling async execution, return types and CompletableFuture, running several calls in parallel, configuring the executor Spring Boot provides (including virtual threads), handling exceptions, and propagating context such as the logged-in user and correlation ids to background threads.
Enabling @Async
Add @EnableAsync to a configuration class. A public method annotated with @Async, called from another bean, then returns immediately while its body runs on a thread from Spring Boot's auto-configured applicationTaskExecutor. As with transactions, it works through proxies: self-invocation and private methods run synchronously.
Return Types
An @Async method may return void (fire and forget) or a CompletableFuture<T> so the caller can wait for, combine or react to the result. CompletableFuture.allOf(...) runs several independent calls in parallel and waits for all of them — a common way to cut response time when a page needs data from three slow services.
The Executor
Spring Boot configures a ThreadPoolTaskExecutor with 8 core threads and an unbounded queue by default; tune it with spring.task.execution.pool.*. An unbounded queue hides overload, so set a queue capacity and max size for production. With spring.threads.virtual.enabled=true (Java 21+), Spring Boot uses a virtual-thread executor instead, which suits I/O-heavy tasks. You can define additional named executors and pick one with @Async("reportExecutor").
Exceptions and Context Propagation
Exceptions from void async methods never reach the caller; handle them with an AsyncUncaughtExceptionHandler or they are only logged. For CompletableFuture methods the exception completes the future exceptionally. Thread-bound context — the SecurityContext, logging MDC, transactions — does not travel to the new thread automatically. Spring Boot applies any TaskDecorator bean to its executors, which is where you copy MDC values; DelegatingSecurityContextAsyncTaskExecutor carries the security context.
When @Async Is Not Enough
@Async work lives only in memory: if the application restarts, queued tasks are lost, and there is no retry. For work that must not be lost — payment processing, order fulfilment — publish a message to a broker (Kafka, RabbitMQ) or use a job framework instead.
Examples
Fire-and-forget email and parallel calls with CompletableFuture
@Configuration
@EnableAsync
public class AsyncConfig {}
@Service
public class NotificationService {
private static final Logger log = LoggerFactory.getLogger(NotificationService.class);
@Async
public void sendWelcomeEmail(String email) {
log.info("Sending welcome email to {} on {}", email, Thread.currentThread().getName());
sleep(2000); // simulate slow SMTP
log.info("Email sent to {}", email);
}
}
@Service
public class DashboardService {
private final StatsClient stats;
public DashboardService(StatsClient stats) {
this.stats = stats;
}
public Dashboard load(String userId) {
CompletableFuture<Progress> progress = stats.progress(userId); // each @Async, ~1s
CompletableFuture<List<Badge>> badges = stats.badges(userId);
CompletableFuture<List<Course>> recs = stats.recommendations(userId);
CompletableFuture.allOf(progress, badges, recs).join();
return new Dashboard(progress.join(), badges.join(), recs.join());
}
}
@Service
public class StatsClient {
@Async
public CompletableFuture<Progress> progress(String userId) {
return CompletableFuture.completedFuture(callRemoteProgressApi(userId));
}
// badges(...) and recommendations(...) are similar
}
POST /api/register -> 201 in 45 ms
INFO [task-1] Sending welcome email to asha@webnest.in on task-1
INFO [task-1] Email sent to asha@webnest.in (2 s later, user already has the response)
GET /api/dashboard -> 200 in ~1.05 s (three 1 s calls in parallel instead of 3 s sequentially)
Configuring the executor, or switching to virtual threads
# application.yml — bounded platform-thread pool
spring:
task:
execution:
thread-name-prefix: async-
pool:
core-size: 8
max-size: 32
queue-capacity: 500
shutdown:
await-termination: true
await-termination-period: 30s
# or, on Java 21+, use virtual threads for all task execution
spring:
threads:
virtual:
enabled: true
INFO [async-3] Sending welcome email ...
(with virtual threads: INFO [async-12] ... — each task on a cheap virtual thread)
Handling exceptions and propagating MDC and security context
@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {
private static final Logger log = LoggerFactory.getLogger(AsyncConfig.class);
@Override
public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
return (ex, method, params) ->
log.error("Async method {} failed with params {}", method.getName(), params, ex);
}
// Spring Boot applies this decorator to the auto-configured executor
@Bean
TaskDecorator contextCopyingDecorator() {
return runnable -> {
Map<String, String> mdc = MDC.getCopyOfContextMap();
SecurityContext security = SecurityContextHolder.getContext();
return () -> {
try {
if (mdc != null) MDC.setContextMap(mdc);
SecurityContextHolder.setContext(security);
runnable.run();
} finally {
MDC.clear();
SecurityContextHolder.clearContext();
}
};
};
}
}
INFO [3b1f6c2e] [async-2] Generating report for asha@webnest.in (correlation id and user carried over)
ERROR AsyncConfig : Async method sendWelcomeEmail failed with params [bad@] MailSendException: Invalid address
Common Mistakes
- Calling an @Async method from the same class and expecting it to run in the background.
- Forgetting @EnableAsync, so every @Async method silently runs synchronously.
- Using @Async for business-critical work that must survive restarts; use a message broker instead.
- Leaving the default unbounded queue in production, hiding overload until memory runs out.
- Expecting SecurityContextHolder or MDC values inside async methods without a TaskDecorator.
Exercise
Using the lesson's Fire-and-forget email and parallel calls with CompletableFuture example, create a small implementation or design sketch that demonstrates @EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor.. Add a test case or scenario that would catch Calling an @Async method from the same class and expecting it to run in the background., and describe the expected result.
Show hints
- Start with Enabling @Async and compare your approach with Fire-and-forget email and parallel calls with CompletableFuture. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows @EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor. and that it would catch the failure described by Calling an @Async method from the same class and expecting it to run in the background..
Quick quiz
1. Which choice is a mistake to avoid in Async Processing with @Async?
- A. @EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor.
- B. Calling an @Async method from the same class and expecting it to run in the background.
- C. Forgetting @EnableAsync, so every @Async method silently runs synchronously.
Show answer
B. Avoid this approach: Calling an @Async method from the same class and expecting it to run in the background. The lesson recommends: @EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor.
Interview questions
How would you apply the guidance in Enabling @Async to a real task, and what failure would you guard against?
Show answer
@EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor. Apply this in Enabling @Async; the example Fire-and-forget email and parallel calls with CompletableFuture shows one way to do it. Avoid Calling an @Async method from the same class and expecting it to run in the background. and explain how your implementation or design prevents that failure.
Key Points to Remember
- @EnableAsync + @Async runs methods on Spring Boot's applicationTaskExecutor.
- Return CompletableFuture to compose results and run independent calls in parallel.
- Tune spring.task.execution.pool.* or enable virtual threads with spring.threads.virtual.enabled.
- Handle void-method exceptions with AsyncUncaughtExceptionHandler.
- Propagate MDC and security context with a TaskDecorator bean.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering