# Integrating Java 21 Virtual Threads with MongoDB and Quarkus for High-Performance Applications
Java 21 marks a significant evolution in concurrent programming with the introduction of Virtual Threads. This feature offers a lightweight, efficient alternative to traditional platform threads, revolutionizing how developers handle concurrency, especially for I/O-bound operations common in database interactions. This guide explores how to leverage Java 21's virtual threads within a Quarkus application interacting with MongoDB, using Eclipse JNoSQL for seamless integration.
Virtual threads are managed by the Java Virtual Machine (JVM) rather than the operating system. They are designed to be incredibly cheap to create and manage, allowing applications to handle thousands, or even millions, of concurrent tasks without the heavy resource footprint associated with platform threads. When a virtual thread encounters a blocking I/O operation (like waiting for a database query response), it yields its underlying carrier thread back to the scheduler, allowing other virtual threads to run. This non-blocking behavior dramatically improves application throughput and responsiveness.
This tutorial demonstrates building a highly responsive, non-blocking application using Quarkus, Java 21, Eclipse JNoSQL, and MongoDB, focusing on harnessing the power of virtual threads for database interactions to reduce latency and enhance scalability.
## Prerequisites
Before starting, ensure you have the following set up:
* Java Development Kit (JDK) 21 or later.
* Apache Maven build tool.
* A running MongoDB instance. You can use:
* MongoDB Atlas (Cloud-based managed service).
* A local instance via Docker. Use the command below to start one:
```shell
docker run --rm -d --name mongodb-instance -p 27017:27017 mongo
```
* A basic Quarkus project configured with MongoDB support via Eclipse JNoSQL. Ensure you are using a recent version of the Quarkus JNoSQL extension.
## Setting Up the Quarkus Project
Ensure your Quarkus project includes the necessary dependency for Eclipse JNoSQL MongoDB integration. Check your `pom.xml` for a dependency similar to this, ensuring the version is appropriate for your Quarkus version (e.g., 3.3.4 or higher):
```xml
<dependency>
<groupId>io.quarkiverse.jnosql</groupId>
<artifactId>quarkus-jnosql-document-mongodb</artifactId>
<version>LATEST_COMPATIBLE_VERSION</version> <!-- Specify the correct version -->
</dependency>
</code></pre>
Next, configure the database name in your <code>src/main/resources/application.properties</code> file:
<pre><code class="language-properties"># Define the database name
jnosql.document.database=cameras
</code></pre>
With the basic setup complete, let's define the data structure for our application.
<h2>Step 1: Define the Data Model (Camera Entity)</h2>
We'll create a <code>Camera</code> entity representing the data stored in MongoDB. This example uses a Java Record for conciseness. We'll also include a static factory method using the <a href="https://www.datafaker.net/">Datafaker</a> library to generate sample data.
Create a <code>Camera.java</code> file in your source directory:
<pre><code class="language-java">import jakarta.nosql.Column;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;
import net.datafaker.Faker;
import org.eclipse.jnosql.mapping.Convert; // Assuming ObjectIdConverter exists or is defined elsewhere
import java.util.UUID;
@Entity
public record Camera(
@Id @Convert(ObjectIdConverter.class) String id, // Assuming ObjectIdConverter handles String to ObjectId mapping if needed
@Column String brand,
@Column String model,
@Column String brandWithModel
) {
public static Camera of(Faker faker) {
var cameraInfo = faker.camera();
String brand = cameraInfo.brand();
String model = cameraInfo.model();
String brandWithModel = cameraInfo.brandWithModel();
// Generate a simple UUID string for the ID, or adapt if using MongoDB ObjectIds directly
return new Camera(UUID.randomUUID().toString(), brand, model, brandWithModel);
}
// Method to create an updated instance based on request data
public Camera update(Camera request) {
// Assumes ID remains the same, updates other fields from the request
return new Camera(this.id, request.brand, request.model, request.brandWithModel);
}
}
</code></pre>
<strong>Key Annotations:</strong>
<ul>
<li><code>@Entity</code>: Identifies this record as a Jakarta NoSQL managed entity.</li>
<li><code>@Id</code>: Marks the <code>id</code> field as the primary identifier.</li>
<li><code>@Column</code>: Specifies that the fields should be mapped to columns/fields in the MongoDB document.</li>
<li><code>@Convert</code>: (Optional) Used here hypothetically if a custom conversion between the Java type (String) and MongoDB's ObjectId is needed via a converter class (<code>ObjectIdConverter</code>).</li>
</ul>
<h2>Step 2: Implement the Business Logic (Camera Service)</h2>
The <code>CameraService</code> acts as the intermediary between the API endpoints and the MongoDB database. It uses Eclipse JNoSQL's <code>DocumentTemplate</code> for data operations and leverages Java 21's virtual threads for asynchronous tasks.
Create a <code>CameraService.java</code> file:
<pre><code class="language-java">import io.quarkus.virtual.threads.VirtualThreads;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import net.datafaker.Faker;
import org.eclipse.jnosql.mapping.document.DocumentTemplate;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.ExecutorService;
import java.util.logging.Logger;
@ApplicationScoped
public class CameraService {
private static final Logger LOGGER = Logger.getLogger(CameraService.class.getName());
private static final Faker FAKER = new Faker();
@Inject
DocumentTemplate template; // Injects the JNoSQL template for MongoDB operations
@Inject
@VirtualThreads // Injects an ExecutorService backed by virtual threads
ExecutorService vThreads;
public List<Camera> findAll() {
LOGGER.info("Selecting all cameras");
return template.select(Camera.class).result();
}
public List<Camera> findByBrand(String brand) {
LOGGER.info("Selecting cameras by brand: " + brand);
return template.select(Camera.class)
.where("brand").like(brand) // Example query
.result();
}
public Optional<Camera> findById(String id) {
LOGGER.info("Finding camera by id: " + id);
return template.find(Camera.class, id);
}
public Camera insert(Camera camera) {
LOGGER.info("Inserting camera: " + camera.id());
return template.insert(camera);
}
public Camera update(Camera camera) {
LOGGER.info("Updating camera: " + camera.id());
return template.update(camera);
}
public void deleteById(String id) {
LOGGER.info("Deleting camera by id: " + id);
template.delete(Camera.class, id);
}
// Asynchronous insertion using virtual threads
public void insertAsync(int size) {
LOGGER.info("Initiating async insertion of " + size + " cameras using virtual threads.");
for (int i = 0; i < size; i++) {
vThreads.submit(() -> {
try {
Camera camera = Camera.of(FAKER);
template.insert(camera);
// Optional: Add logging inside the thread if needed
// LOGGER.info("Async inserted camera: " + camera.id() + " on thread: " + Thread.currentThread());
} catch (Exception e) {
LOGGER.severe("Error inserting camera asynchronously: " + e.getMessage());
}
});
}
LOGGER.info("Submitted all " + size + " async insertion tasks.");
}
}
</code></pre>
In this service:
* <code>DocumentTemplate</code> simplifies CRUD operations against MongoDB.
* The <code>ExecutorService</code> annotated with <code>@VirtualThreads</code> is provided by Quarkus. When <code>vThreads.submit()</code> is called, the task (inserting a camera) runs on a virtual thread, making the <code>insertAsync</code> method highly efficient for bulk operations without blocking the main request thread.
<h2>Step 3: Expose the API (Camera Resource)</h2>
Create a RESTful API endpoint using Jakarta REST (JAX-RS) to expose the camera operations. The <code>CameraResource</code> class will handle incoming HTTP requests and delegate them to the <code>CameraService</code>.
Create a <code>CameraResource.java</code> file:
<pre><code class="language-java">import io.quarkus.virtual.threads.VirtualThreads; // Import if using @VirtualThreads on methods
import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;
@Path("/cameras")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CameraResource {
@Inject
CameraService service;
// Example: Using @VirtualThreads directly on a JAX-RS method
// This tells Quarkus to run this specific endpoint logic on a virtual thread.
@GET
@VirtualThreads
public List<Camera> findAll() {
// The service call itself might be blocking,
// running it on a VT prevents blocking the carrier thread.
return service.findAll();
}
@GET
@Path("/brand/{brand}")
public List<Camera> findByBrand(@PathParam("brand") String brand) {
// Basic validation example
if (brand == null || brand.isBlank()) {
throw new WebApplicationException("Brand parameter cannot be empty", Response.Status.BAD_REQUEST);
}
return service.findByBrand(brand);
}
@GET
@Path("/{id}")
public Camera get(@PathParam("id") String id) {
return service.findById(id)
.orElseThrow(() -> new WebApplicationException("Camera not found", Response.Status.NOT_FOUND));
}
@POST
public Response add(Camera camera) {
// Basic validation example
if (camera == null || camera.brand() == null || camera.model() == null) {
throw new WebApplicationException("Invalid camera data provided", Response.Status.BAD_REQUEST);
}
Camera createdCamera = service.insert(camera);
// Return 201 Created status with the created resource
return Response.status(Response.Status.CREATED).entity(createdCamera).build();
}
@PUT
@Path("/{id}")
public Camera update(@PathParam("id") String id, Camera request) {
Camera existingCamera = service.findById(id)
.orElseThrow(() -> new WebApplicationException("Camera not found for update", Response.Status.NOT_FOUND));
// Use the update method from the Camera record/class
Camera cameraToUpdate = existingCamera.update(request);
return service.update(cameraToUpdate);
}
@DELETE
@Path("/{id}")
public Response delete(@PathParam("id") String id) {
// Ensure the camera exists before attempting deletion (optional but good practice)
service.findById(id)
.orElseThrow(() -> new WebApplicationException("Camera not found for deletion", Response.Status.NOT_FOUND));
service.deleteById(id);
// Return 204 No Content on successful deletion
return Response.noContent().build();
}
// Endpoint to trigger asynchronous insertion via the service
@POST
@Path("/async")
public Response insertCamerasAsync(@QueryParam("size") @DefaultValue("100") int size) {
if (size <= 0) {
throw new WebApplicationException("Size parameter must be positive", Response.Status.BAD_REQUEST);
}
service.insertAsync(size);
// Return 202 Accepted as the process is initiated asynchronously
return Response.accepted("Async insertion of " + size + " cameras initiated.").build();
}
}
</code></pre>
Notice the <code>@VirtualThreads</code> annotation can also be applied directly to JAX-RS resource methods (like <code>findAll</code>), instructing Quarkus to execute that specific request handling logic on a virtual thread.
<h2>Step 4: Build and Run the Application</h2>
With the code in place, build the application using Maven and run the resulting JAR file. Ensure your MongoDB instance is accessible.
<pre><code class="language-shell"># Build the application package (uber-jar)
mvn clean package -Dquarkus.package.type=uber-jar
# Run the application
java -jar target/quarkus-app/quarkus-run.jar
# Note: The exact path/name might vary based on your project's artifactId/version
</code></pre>
<h2>Step 5: Test the API</h2>
Once the application is running, you can interact with the API using <code>curl</code> or any HTTP client. Replace <code>{id}</code> with an actual camera ID obtained from creation or listing.
<strong>Create a Camera:</strong>
<pre><code class="language-shell">curl -X POST -H "Content-Type: application/json" -d '{
"brand": "Sony",
"model": "Alpha 7 IV",
"brandWithModel": "Sony Alpha 7 IV"
}' http://localhost:8080/cameras
</code></pre>
<strong>Get All Cameras:</strong>
<pre><code class="language-shell">curl -X GET http://localhost:8080/cameras
</code></pre>
<strong>Get Cameras by Brand:</strong>
<pre><code class="language-shell">curl -X GET http://localhost:8080/cameras/brand/Sony
</code></pre>
<strong>Get a Camera by ID:</strong>
<pre><code class="language-shell">curl -X GET http://localhost:8080/cameras/{id}
</code></pre>
<strong>Update a Camera by ID:</strong>
<pre><code class="language-shell">curl -X PUT -H "Content-Type: application/json" -d '{
"brand": "Sony",
"model": "Alpha 7 V",
"brandWithModel": "Sony Alpha 7 V"
}' http://localhost:8080/cameras/{id}
</code></pre>
<strong>Delete a Camera by ID:</strong>
<pre><code class="language-shell">curl -X DELETE http://localhost:8080/cameras/{id}
</code></pre>
<strong>Insert Cameras Asynchronously:</strong>
Trigger the bulk insertion using virtual threads. The <code>size</code> parameter is optional (defaults to 100).
<pre><code class="language-shell">curl -X POST http://localhost:8080/cameras/async?size=500
</code></pre>
You should receive a <code>202 Accepted</code> response immediately, and the insertions will proceed in the background using virtual threads.
<h2>Conclusion</h2>
Java 21's virtual threads offer a powerful yet simple way to handle I/O-bound concurrency, dramatically improving the scalability and responsiveness of applications interacting with databases like MongoDB. By integrating virtual threads with Quarkus and Eclipse JNoSQL, developers can build high-performance applications using familiar synchronous coding styles while benefiting from non-blocking execution under the hood. This approach minimizes resource overhead and simplifies the development of modern, concurrent Java applications.
<hr />
<strong>Leverage Modern Java Concurrency with Innovative Software Technology</strong>
Need to enhance your Java applications for superior concurrency and performance? At Innovative Software Technology, we specialize in harnessing cutting-edge Java features like Virtual Threads, alongside powerful frameworks like Quarkus and NoSQL databases such as MongoDB. Our expert Java development team excels at designing, building, and modernizing scalable, high-performance software solutions. Partner with us to optimize your applications, ensuring they efficiently manage demanding workloads and leverage the full potential of Java's latest advancements for unparalleled responsiveness and resource utilization. Contact Innovative Software Technology today to discuss your custom Java application development and performance optimization needs.
```