Hibernate Reactive and Quarkus

1. Overview

Creating reactive applications for large-scale, high-performance systems has become increasingly essential in Java development. Hibernate Reactive and Quarkus are powerful tools that enable developers to build reactive applications efficiently. Hibernate Reactive is a reactive extension of Hibernate ORM, designed to work with non-blocking database drivers seamlessly.

On the other hand, Quarkus is a Kubernetes-native Java framework optimized for GraalVM and OpenJDK HotSpot, tailored explicitly for building reactive applications. Together, they provide a robust platform for creating high-performance, scalable, and reactive Java applications.

In this tutorial, we’ll explore Hibernate Reactive and Quarkus in-depth by building a reactive bank deposit application from scratch. Additionally, we’ll incorporate integration tests to ensure the application’s correctness and reliability.

2. Reactive Programming in Quarkus

Quarkus, renowned as a reactive framework, has embraced reactivity as a fundamental element of its architecture right from the outset. The framework is enriched with a multitude of reactive features and is backed by a robust ecosystem.

Notably, Quarkus harnesses reactive concepts through the Uni and Multi types provided by Mutiny, demonstrating a strong commitment to asynchronous and event-driven programming paradigms.

3. Mutiny in Quarkus

Mutiny is the main API used to handle reactive features in Quarkus. Most extensions support Mutiny by providing an API that returns Uni and Multi, which handles asynchronous data streams with non-blocking backpressure.

Our application utilizes reactive concepts through Uni and Multi types provided by Quarkus. Multi represents a type that can emit multiple items asynchronously, similar to java.util.stream.Stream but with backpressure handling.

We use Multi when processing a potentially unbounded data stream, like streaming multiple bank deposits in real time.

Uni represents a type that emits at most one item or an error, similar to java.util.concurrent.CompletableFuture but with more powerful composition operators. Uni is used for scenarios where we expect either a single result or an error, such as fetching a single bank deposit from the database.

4. Understanding PanacheEntity

When we use Quarkus with Hibernate Reactive, the PanacheEntity class offers a streamlined approach to defining JPA entities with minimal boilerplate code. By extending from Hibernate’s PanacheEntityBase, PanacheEntity gains reactive capabilities, enabling entities to be managed in a non-blocking manner.

This allows for efficient handling of database operations without blocking the application’s execution, resulting in improved overall performance.

5. Maven Dependency

First we add the quarkus-hibernate-reactive-panache dependency to our pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-reactive-panache</artifactId>
    <version>3.11.0</version>
</dependency>

Now we have the dependency configured, we can move on to use it in our sample implementation.

6. Real World Example Code

It’s common for high demands to be placed on banking systems. We can implement crucial services using technologies such as Quarkus, Hibernate, and reactive programming to address this.

For this example, we’ll focus on implementing two specific services: creating bank deposits and listing and streaming all bank deposits.

6.1. Create Bank Deposit Entity

The ORM (Object-Relational Mapping) entity is crucial to every CRUD-based system. This entity allows for mapping database objects to the object model in software, facilitating data manipulation. Additionally, it’s essential to properly define the Deposit entity to ensure the smooth functioning of the system and accurate data management:

@Entity
public class Deposit extends PanacheEntity {
    public String depositCod;
    public String currency;
    public String amount;  
    // standard setters and getters
}

In this specific example, the class Deposit extends the PanacheEntity class, effectively making it a reactive entity managed by Hibernate Reactive.

As a result of this extension, the Deposit class inherits methods for CRUD (Create, Read, Update, Delete) operations and gains query capabilities, significantly reducing the need for manual SQL or JPQL queries within the application. This approach simplifies the database operations management and enhances the system’s overall efficiency.

6.2. Implementing Repository

In most cases, we typically utilize the deposit entity for all our CRUD operations. However, in this particular scenario, we’ve created a dedicated DepositRepository:

@ApplicationScoped
public class DepositRepository {

    @Inject
    Mutiny.SessionFactory sessionFactory;

    @Inject
    JDBCPool client;

    public Uni<Deposit> save(Deposit deposit) {
        return sessionFactory.withTransaction((session, transaction) -> session.persist(deposit)
          .replaceWith(deposit));
    }

    public Multi<Deposit> streamAll() {
        return client.query("SELECT depositCode, currency,amount FROM Deposit ")
          .execute()
          .onItem()
          .transformToMulti(set -> Multi.createFrom()
            .iterable(set))
          .onItem()
          .transform(Deposit::from);
    }
}

This repository creates a custom save() method and a streamAll() method, allowing us to retrieve all deposits in a Multi<Deposit> format.

6.3. Implement REST Endpoint

Now is the time to expose our reactive methods using the REST endpoints:

@Path("/deposits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class DepositResource {

    @Inject
    DepositRepository repository;

    @GET
    public Uni<Response> getAllDeposits() {
        return Deposit.listAll()
          .map(deposits -> Response.ok(deposits)
            .build());
    }

    @POST
    public Uni<Response> createDeposit(Deposit deposit) {
        return deposit.persistAndFlush()
          .map(v -> Response.status(Response.Status.CREATED)
            .build());
    }

    @GET
    @Path("stream")
    public Multi<Deposit> streamDeposits() {
      return repository.streamAll();
    }
}

As we can see, the REST service has three reactive methods: getAllDeposits(), that returns all deposits in a Uni<Response> type, and we also have the method createDeposit(), that creates deposits. Both of these methods have a return type of Uni<Response>, whereas streamDeposits() returns Multi<Deposit>.

7. Testing

To ensure the accuracy and dependability of our application, we’ll incorporate integration tests using JUnit and @QuarkusTest. This approach involves creating tests to validate individual codes or components of the software to verify their proper functionality and performance. These tests help us identify and correct any issues early in development, ultimately leading to a more robust and reliable application:

@QuarkusTest
public class DepositResourceIntegrationTest {

    @Inject
    DepositRepository repository;

    @Test
    public void givenAccountWithDeposits_whenGetDeposits_thenReturnAllDeposits() {
        given().when()
          .get("/deposits")
          .then()
          .statusCode(200);
   }
}

The test we discussed focuses solely on validating the successful connection to the REST endpoint and creating a deposit. However, it’s essential to note that not all tests are as straightforward. Testing reactive Panache entities in a @QuarkusTest introduces added complexity compared to testing regular Panache entities.

This complexity arises from the asynchronous nature of the APIs and the imperative requirement that all operations must execute on a Vert.x event loop.

First of all, we add the quarkus-test-hibernate-reactive-panache dependency with the test scope to our pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-test-hibernate-reactive-panache</artifactId>
    <version>3.3.3</version>
    <scope>test</scope>
</dependency>

The integration test methods should be annotated with @RunOnVertxContext, which allows them to run on a Vert.x thread instead of the main thread.

This annotation is particularly useful for testing components that must be executed on the Event Loop, providing a more accurate simulation of real-world conditions.

TransactionalUniAsserter is the expected input type for unit test methods. It functions like an interceptor, wrapping each assert method within its own reactive transaction. This allows for more precise management of the test environment and ensures that each assert method operates within its own isolated context:

@Test
@RunOnVertxContext
public void givenDeposit_whenSaveDepositCalled_ThenCheckCount(TransactionalUniAsserter asserter){
    asserter.execute(() -> repository.save(new Deposit("DEP20230201","10","USD")));
    asserter.assertEquals(() -> Deposit.count(), 2l);
}

Now, we need to write a test for our streamDeposit() , which returns Multi<Deposit>:

@Test
public void givenDepositsInDatabase_whenStreamAllDeposits_thenDepositsAreStreamedWithDelay() {
    Deposit deposit1 = new Deposit("67890", "USD", "200.0");
    Deposit deposit2 = new Deposit("67891", "USD", "300.0");
    repository.save(deposit1)
      .await()
      .indefinitely();
    repository.save(deposit2)
      .await()
      .indefinitely();
    Response response = RestAssured.get("/deposits/stream")
      .then()
      .extract()
      .response();

    // Then: the response contains the streamed books with a delay
    response.then()
      .statusCode(200);
    response.then()
      .body("$", hasSize(2));
    response.then()
      .body("[0].depositCode", equalTo("67890"));
    response.then()
      .body("[1].depositCode", equalTo("67891"));
}

The purpose of this test is to validate the functionality of streaming deposits to retrieve all accounts using the Multi<Deposit> type in a reactive manner.

8. Conclusion

In this article, we explored the concepts of reactive programming using Hibernate Reactive and Quarkus. We discussed the basics of Uni and Multi, and included a integration test to verify the correctness of our code.

Reactive programming with Hibernate Reactive and Quarkus allows for efficient, non-blocking database operations, making applications more responsive and scalable. By leveraging these tools, we can build modern, cloud-native applications that meet the demands of today’s high-performance environments.