How to Use Virtual Threads in Java (Project Loom) with Spring Boot

Virtual threads are one of the most exciting additions to modern Java. They make it much easier to write highly concurrent applications without the complexity of managing large thread pools, callbacks, or reactive pipelines.

If you build applications with Spring Boot, virtual threads can help your app handle many more concurrent tasks with simpler code.

In this post, we’ll cover:

  • What virtual threads are
  • Why they matter
  • When to use them
  • How to enable them in Spring Boot
  • A few important best practices and warnings

What are virtual threads?

Traditional Java threads are often called platform threads. They are mapped closely to operating system threads. That means they are relatively expensive in terms of memory and scheduling.

Virtual threads are lightweight threads managed by the JVM, not directly by the operating system. They are designed to make blocking code cheap again.

In simple terms:

  • Platform threads = heavier, fewer, more expensive
  • Virtual threads = lightweight, many more, cheaper to create

This means you can write code in the usual imperative style, but still support high concurrency.


Why virtual threads matter

For years, Java developers had two main choices for handling concurrency:

  1. Use thread pools and blocking code
  2. Use asynchronous/reactive programming

Virtual threads give you a third option:

  • Keep the simple blocking style
  • Avoid the complexity of reactive code
  • Scale better under lots of concurrent I/O operations

This is especially useful for applications that spend a lot of time waiting on:

  • Database calls
  • HTTP requests
  • File I/O
  • Remote service calls

If your application is mostly I/O-bound, virtual threads can be a great fit.


Virtual threads vs platform threads

Here’s a simple comparison:

Feature Platform Threads Virtual Threads
Cost to create Higher Very low
Memory usage Higher Lower
Number you can run Limited Much larger
Good for blocking code Yes, but expensive Yes, and efficient
Managed by OS Yes Mostly by JVM

The biggest win is that virtual threads let you run many blocking tasks concurrently without exhausting thread resources as quickly.


When should you use virtual threads?

Virtual threads are a strong choice when your app does lots of blocking I/O and you want simple code.

Good use cases:

  • REST APIs with many simultaneous requests
  • Service-to-service communication
  • Database-heavy applications
  • Background jobs that wait on I/O
  • File processing or batch operations

Less ideal use cases:

  • CPU-intensive tasks
  • Work that depends heavily on thread-local assumptions
  • Libraries that block while holding locks in a problematic way

Virtual threads do not magically make CPU-bound code faster. They help most when threads spend time waiting.


Project Loom in Java

Virtual threads are part of Project Loom, a long-running effort to modernize concurrency in Java.

Loom also introduced other improvements around structured concurrency and scoped values, but the headline feature most developers use today is virtual threads.

Virtual threads became a standard Java feature in recent releases, so you no longer need special preview settings in modern Java versions.


How Spring Boot supports virtual threads

Spring Boot has first-class support for virtual threads.

If you are using Spring Boot 3.2+, you can usually enable them with a simple configuration property:

spring.threads.virtual.enabled=true

That tells Spring Boot to use virtual threads in places where it manages request handling and task execution.

This is one of the nicest parts: in many cases, you can get the benefits of virtual threads with very little code change.


Basic setup in Spring Boot

1. Use a recent Java version

Virtual threads require a modern JDK, for example Java 25.

2. Use a recent Spring Boot version

Make sure your Spring Boot version supports virtual threads well. Spring Boot 3.2 or later is recommended.

3. Enable virtual threads

Add this to your application configuration:

spring.threads.virtual.enabled=true

Or in YAML:

spring:
  threads:
    virtual:
      enabled: true

That’s often enough for web applications.


What happens when you enable them?

When virtual threads are enabled, Spring can use them for tasks such as:

  • Handling incoming HTTP requests
  • Running @Async methods
  • Executing some scheduled or background tasks

The exact behavior depends on the Spring component and configuration, but the overall idea is that work can run on virtual threads instead of a small pool of platform threads.


Example: a Spring Boot REST controller

Here is a simple example of how your code can stay clean and blocking while still benefiting from virtual threads.

package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    private final DemoService demoService;

    public DemoController(DemoService demoService) {
        this.demoService = demoService;
    }

    @GetMapping("/hello")
    public String hello() {
        return demoService.fetchMessage();
    }
}
package com.example.demo;

import org.springframework.stereotype.Service;

@Service
public class DemoService {

    public String fetchMessage() {
        // Simulate a blocking operation
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return "Hello from a virtual thread!";
    }
}

With virtual threads enabled, each request can be handled with a lightweight thread, even though the service method blocks.


Example: using virtual threads for background tasks

You can also create virtual threads manually when needed.

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class VirtualThreadExample {

    public static void main(String[] args) {
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            executor.submit(() -> System.out.println("Task 1 on virtual thread"));
            executor.submit(() -> System.out.println("Task 2 on another virtual thread"));
        }
    }
}

This is useful when you want a simple executor that creates a new virtual thread for each task.


Using @Async with virtual threads

Spring’s @Async support can also benefit from virtual threads.

For example:

package com.example.demo;

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

import java.util.concurrent.CompletableFuture;

@Service
public class EmailService {

    @Async
    public CompletableFuture<String> sendEmail() {
        // Simulate work
        return CompletableFuture.completedFuture("Email sent");
    }
}

If Spring is configured to use virtual threads for task execution, these async methods can run on virtual threads, making blocking work much cheaper.


Virtual threads do not replace everything

It’s important not to oversell virtual threads. They solve one problem very well: cheap blocking concurrency.

They do not replace:

  • Proper database indexing
  • Efficient network design
  • Good application architecture
  • Caching
  • Load balancing
  • Performance tuning

Virtual threads are a concurrency tool, not a performance silver bullet.


Best practices when using virtual threads

1. Keep code simple

One of the main advantages of virtual threads is that you can keep using normal blocking code. Don’t add unnecessary complexity.

2. Avoid long synchronized blocks

Virtual threads can behave poorly if they spend too much time blocked inside synchronized sections. Prefer shorter critical sections and consider alternatives where appropriate.

3. Watch out for thread-local usage

Some older code relies heavily on ThreadLocal. Virtual threads support it, but large-scale usage can still create complexity and memory overhead.

4. Test your dependencies

Most modern libraries work well, but some older libraries may assume platform-thread behavior or may not play nicely with high concurrency.

5. Don’t use virtual threads for CPU-heavy work expecting miracles

If your bottleneck is CPU, virtual threads will not fix it. For CPU-bound tasks, focus on algorithms, parallelism, and profiling.


Common questions

Are virtual threads faster?

Not always in a direct “single task runs faster” sense. Their big advantage is that they allow more concurrency with less overhead, especially for blocking I/O.

Do I need reactive programming anymore?

Not necessarily. Virtual threads reduce the need for reactive programming in many applications, especially if you prefer imperative code.

Can I use virtual threads with Spring MVC?

Yes. Spring MVC is a great fit because it already uses a blocking request model, which maps naturally to virtual threads.

Can I use them with Spring WebFlux?

You can, but WebFlux is built around a reactive model. Virtual threads are often more valuable in traditional blocking stacks like Spring MVC.


When virtual threads are a great fit in Spring Boot

Virtual threads are especially attractive if:

  • You already have a Spring MVC application
  • You use JDBC and blocking database access
  • Your codebase is imperative and you want to keep it that way
  • You want to handle more concurrent requests with less thread-pool tuning

In many cases, virtual threads let you modernize your app without rewriting it.


A practical migration strategy

If you want to adopt virtual threads in an existing Spring Boot app, here’s a simple approach:

  1. Upgrade to a compatible Java and Spring Boot version
  2. Enable virtual threads in configuration
  3. Test your main request paths
  4. Watch application metrics under load
  5. Check library compatibility
  6. Tune only where needed

You usually do not need to rewrite your whole application.


Final thoughts

Virtual threads are a major step forward for Java concurrency. They make it possible to write straightforward, blocking-style code while still supporting high throughput and scalability.

For Spring Boot developers, this is especially valuable because it means:

  • Less concurrency boilerplate
  • Easier-to-read code
  • Better scaling for I/O-heavy workloads
  • A smoother path than fully reactive programming for many apps

If your application spends a lot of time waiting on I/O, virtual threads are absolutely worth trying.


Summary

Use virtual threads in Spring Boot when you want:

  • Simple blocking code
  • High concurrency
  • Less thread-pool management
  • Better scalability for I/O-bound workloads

Enable them with:

spring.threads.virtual.enabled=true

Then test, measure, and enjoy a much simpler concurrency model in Java.

Testing Spring Boot Applications with JUnit and Mockito

Testing Spring Boot applications with JUnit and Mockito is a good practice to ensure the correctness and reliability of your application. Below, I’ll present a brief overview of how to write such test cases with explanations and examples.

1. JUnit Basics in Spring Boot

Spring Boot provides out-of-the-box support for JUnit through the spring-boot-starter-test dependency, which includes:

  • JUnit 5 (Jupiter) for writing test cases.
  • Mockito for mocking dependencies.
  • Additional libraries like Hamcrest and AssertJ for assertions.

Add the dependency in your pom.xml (if it’s not already present):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

2. Structural Overview

Testing can be divided into:

  • Unit Tests: Independent and isolated tests of individual classes, written using JUnit + Mockito.
  • Integration Tests: Testing multiple layers/classes, typically with Spring’s @SpringBootTest.

3. Writing Unit Tests with JUnit and Mockito

Below is an example of unit testing a Service class.

Example Scenario:

We have a class that depends on UserRepository. UserService
UserService.java:

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public User findUserById(Long id) {
        return userRepository.findById(id).orElseThrow(() -> new RuntimeException("User not found"));
    }
}

UserRepository.java:

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

Corresponding Test Case

@ExtendWith(MockitoExtension.class) // Enables Mockito in JUnit 5
class UserServiceTest {

    @Mock // Creates a mock instance of UserRepository
    private UserRepository userRepository;

    @InjectMocks // Creates UserService and injects the mock UserRepository
    private UserService userService;

    @Test
    void testFindUserById_UserExists() {
        // Arrange
        Long userId = 1L;
        User mockUser = new User(userId, "John Doe", "[email protected]");

        // Mock the behavior of userRepository
        Mockito.when(userRepository.findById(userId)).thenReturn(Optional.of(mockUser));

        // Act
        User result = userService.findUserById(userId);

        // Assert
        assertNotNull(result);
        assertEquals(mockUser.getName(), result.getName());
        Mockito.verify(userRepository).findById(userId); // Verify method call
    }

    @Test
    void testFindUserById_UserNotFound() {
        // Arrange
        Long userId = 1L;

        // Mock the behavior of userRepository
        Mockito.when(userRepository.findById(userId)).thenReturn(Optional.empty());

        // Act & Assert
        Exception exception = assertThrows(RuntimeException.class, () -> userService.findUserById(userId));
        assertEquals("User not found", exception.getMessage());
    }
}

4. Integration Tests with @SpringBootTest

Integration tests are used to test the entire Spring application context.

Testing UserController

UserController.java:

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return ResponseEntity.ok(userService.findUserById(id));
    }
}

Test Case for UserController

Use @SpringBootTest with for integration-like testing. MockMvc

@SpringBootTest
@AutoConfigureMockMvc // Configures MockMvc
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean // Mock a bean in the Spring context
    private UserService userService;

    @Test
    void testGetUserById() throws Exception {
        // Arrange
        Long userId = 1L;
        User mockUser = new User(userId, "John Doe", "[email protected]");

        Mockito.when(userService.findUserById(userId)).thenReturn(mockUser);

        // Act and Assert
        mockMvc.perform(get("/users/{id}", userId))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("John Doe"))
               .andExpect(jsonPath("$.email").value("[email protected]"));

        Mockito.verify(userService).findUserById(userId);
    }
}

5. Tips for Effective Testing

  1. Mock dependencies: Mock all external dependencies to isolate the unit being tested.
  2. Use Assertions effectively: Leverage libraries like AssertJ or Hamcrest for expressive assertions.
  3. Test exceptions: Always test boundary cases and exceptions.
  4. Verify mock behavior: Use Mockito.verify() to ensure mocked methods were invoked correctly.
  5. Spring utilities: @MockBean is useful for overriding beans in the application context for integration testing.

Summary

Spring Boot testing with JUnit and Mockito allows you to:

  • Write isolated unit tests for business logic.
  • Write integration tests to validate Spring components working together.

Implementing Global Exception Handling with @ControllerAdvice

To implement global exception handling in a Spring application, the @ControllerAdvice annotation is used. It allows you to centralize exception handling across multiple controllers.

Below is an example of how you can implement global exception handling with @ControllerAdvice in your application:


1. Define a Global Exception Handler

Create a class with the @ControllerAdvice annotation to handle exceptions globally. Within this class, use the @ExceptionHandler annotation on methods to define specific exception handling logic.

package org.kodejava;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;

// Marks this class as a global exception handler
@ControllerAdvice
public class GlobalExceptionHandler {

    // Handle specific exceptions
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<?> handleResourceNotFoundException(ResourceNotFoundException ex, WebRequest request) {
        ErrorResponse errorResponse = new ErrorResponse(
                HttpStatus.NOT_FOUND.value(),
                ex.getMessage(),
                request.getDescription(false));
        return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
    }

    // Handle global exceptions (for all other exceptions)
    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleGlobalException(Exception ex, WebRequest request) {
        ErrorResponse errorResponse = new ErrorResponse(
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                "An unexpected error occurred",
                request.getDescription(false));
        return new ResponseEntity<>(errorResponse, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

2. Create a Custom Exception Class (Optional)

Define specific exception classes for your business use cases. For example, a ResourceNotFoundException for handling “not found” errors.

package org.kodejava;

public class ResourceNotFoundException extends RuntimeException {

    private static final long serialVersionUID = 1L;

    public ResourceNotFoundException(String message) {
        super(message);
    }
}

3. Create an Error Response Model

Create a class to structure the error response data consistently.

package org.kodejava;

public class ErrorResponse {

    private int statusCode;
    private String message;
    private String details;

    public ErrorResponse(int statusCode, String message, String details) {
        this.statusCode = statusCode;
        this.message = message;
        this.details = details;
    }

    // Getters and Setters
    public int getStatusCode() {
        return statusCode;
    }

    public void setStatusCode(int statusCode) {
        this.statusCode = statusCode;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getDetails() {
        return details;
    }

    public void setDetails(String details) {
        this.details = details;
    }
}

4. Throw Custom Exceptions in Your Controller

You can now throw the ResourceNotFoundException or other exceptions in your controllers, and let the global exception handler process them.

package org.kodejava;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class TestController {

    @GetMapping("/resource")
    public String getResource() {
        throw new ResourceNotFoundException("Resource not found with ID");
    }
}

5. Test the Application

When you access the /api/resource endpoint, the global exception handler will catch the ResourceNotFoundException and return a structured error response. Example response:

{
  "statusCode": 404,
  "message": "Resource not found with ID",
  "details": "uri=/api/resource"
}

Advantages of Using @ControllerAdvice

  1. Centralized Exception Handling: Removes the need to write exception handling in multiple controllers.
  2. Improved Readability: Controllers are cleaner as they no longer handle exceptions.
  3. Reusability: Reuse the exception handler for different types of exceptions across the application.
  4. Custom Responses: Provides flexibility to return consistent error responses.

This implementation ensures your application has a robust and maintainable error-handling mechanism using Spring’s @ControllerAdvice.

Using Lombok in Spring Boot to Reduce Boilerplate Code

Lombok is an excellent library for reducing boilerplate code in Java applications, including Spring Boot projects. It provides useful annotations that simplify mundane tasks like generating getters, setters, constructors, hashCode, equals, and toString methods.

Here’s how to use Lombok in a Spring Boot project to make your code cleaner and more concise:

Steps to Use Lombok in Spring Boot

  1. Add Lombok Dependency
    Add the Lombok dependency to your (for Maven) or build.gradle (for Gradle). pom.xml
    Maven:

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.30</version> <!-- Check for the latest version -->
        <scope>provided</scope>
    </dependency>
    
  2. Enable Annotation Processing
    Ensure that annotation processing is enabled in your IDE (e.g., IntelliJ IDEA).
    In IntelliJ IDEA:

    • Go to File > Settings > Build, Execution, Deployment > Compiler > Annotation Processors.
    • Check Enable annotation processing.
  3. Add Lombok Annotations in Your Code
    Use Lombok annotations in your classes to reduce boilerplate code. The most commonly used annotations are described below.

Commonly Used Lombok Annotations

  1. @Getter and @Setter
    Automatically generates getter and setter methods for your fields.

    import lombok.Getter;
    import lombok.Setter;
    
    @Getter
    @Setter
    public class User {
        private Long id;
        private String name;
    }
    
  2. @ToString
    Automatically generates a toString() method for the class.

    import lombok.ToString;
    
    @ToString
    public class User {
        private Long id;
        private String name;
    }
    
  3. @EqualsAndHashCode
    Generates equals() and hashCode() methods.

    import lombok.EqualsAndHashCode;
    
    @EqualsAndHashCode
    public class User {
        private Long id;
        private String name;
    }
    
  4. @NoArgsConstructor, @AllArgsConstructor, @RequiredArgsConstructor
    Generates constructors:

    • @NoArgsConstructor: No-args constructor.
    • @AllArgsConstructor: All-args constructor.
    • @RequiredArgsConstructor: Constructor for required fields (final fields or fields with @NonNull annotation).
    import lombok.AllArgsConstructor;
    import lombok.NoArgsConstructor;
    import lombok.RequiredArgsConstructor;
    
    @NoArgsConstructor
    @AllArgsConstructor
    @RequiredArgsConstructor
    public class User {
        private Long id;
        @NonNull
        private String name;
    }
    
  5. @Data
    A shorthand annotation that combines @Getter, @Setter, @ToString, @EqualsAndHashCode, and @RequiredArgsConstructor.

    import lombok.Data;
    
    @Data
    public class User {
        private Long id;
        private String name;
    }
    
  6. @Builder
    Enables the builder pattern for the class.

    import lombok.Builder;
    
    @Builder
    public class User {
        private Long id;
        private String name;
    }
    
  7. @Slf4j
    Adds a static logger variable (log) for logging purposes.

    import lombok.extern.slf4j.Slf4j;
    
    @Slf4j
    public class UserService {
        public void performAction() {
            log.info("Performing some action...");
        }
    }
    

Example: Lombok in a Spring Boot Entity

Below is an example of a Spring Boot entity class that uses Lombok annotations:

package com.example.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import lombok.Data;
import lombok.NoArgsConstructor;

@Entity
@Data
@NoArgsConstructor
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
}

Logging Example

Service class adding logging with Lombok’s @Slf4j:

package com.example.demo.service;

import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@Slf4j
public class UserService {
    public void processUser() {
        log.info("Processing user...");
    }
}

Advantages of Using Lombok

  1. Significant reduction in boilerplate code, making your classes cleaner and easier to read.
  2. Easier maintenance since redundant code is removed.
  3. Integration with Spring Boot makes it seamless to use.

Understanding @Entity, @Repository, and @Service in Spring Boot

In Spring Boot (and the larger Spring Framework), the annotations @Entity, @Repository, and @Service play a key role in structuring and organizing applications using the principles of dependency injection and inversion of control. Here’s an overview of each:


1. @Entity

  • Definition: The @Entity annotation is used in Java Persistence API (JPA) to define a class as a persistent entity. This means the class maps to a table in the database.
  • Key Features:
    • Marks a POJO (Plain Old Java Object) as a JPA entity.
    • Each annotated class is associated with a database table, and each instance of the class represents a row in that table.
    • Requires a primary key, typically annotated with @Id.
  • Example:

package org.kodejava.spring;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;

@Entity
public class Employee {
    @Id
    private Long id;
    private String name;
    private String role;

    // Getters and setters
}
  • Usage Context: This annotation is part of Jakarta EE (or JPA) and is generally used for classes that model database tables.

2. @Repository

  • Definition: The @Repository annotation indicates that the class is a repository, which is responsible for interacting with the database.
  • Key Features:

    • Used for Data Access Objects (DAO).
    • It helps encapsulate the interaction with the database from the rest of the application.
    • It automatically translates exceptions thrown by the persistence layer into Spring’s unchecked exceptions (like DataAccessException).
  • Example:

package org.kodejava.spring;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface EmployeeRepository extends JpaRepository<Employee, Long> {
    // Custom database queries (if needed)
}
  • Usage Context: Typically, @Repository is used to annotate interfaces or classes that handle data persistence, often enhanced by Spring Data JPA for reducing boilerplate code.

3. @Service

  • Definition: The @Service annotation marks a class as a business service that contains the application’s business logic.
  • Key Features:

    • Indicates that the class is a “service” component in the Service layer.
    • Helps clearly separate business logic from other concerns, such as data persistence or presentation.
    • Works in conjunction with @Component to allow dependency injection.
  • Example:

package org.kodejava.spring;

import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class EmployeeService {
    private final EmployeeRepository repository;

    // Constructor injection of the repository
    public EmployeeService(EmployeeRepository repository) {
        this.repository = repository;
    }

    public List<Employee> getAllEmployees() {
        return repository.findAll();
    }

    public Employee saveEmployee(Employee employee) {
        return repository.save(employee);
    }
}
  • Usage Context: Typically used to encapsulate and reuse business logic.

Summary of Their Responsibilities in an Application Layer:

  • @Entity: Maps a Java class to a database table (used in the Data Model layer).
  • @Repository: Handles database operations (typically at the Data Access layer).
  • @Service: Contains business logic (used in the Service layer).

How These Work Together:

These annotations correspond to different tiers in a common layering structure of a Spring Boot application:
1. Entity: Represents data (e.g., Employee).
2. Repository: Provides the CRUD operations for entities using JPA (e.g., EmployeeRepository).
3. Service: Manages the application’s business logic and interactions (e.g., EmployeeService).

By using these annotations together, you achieve a clean separation of concerns, making the application easier to maintain, test, and scale.