Table of Contents

Micronaut MongoDB Asynchronous

Learn how to use a non-blocking reactive streams MongoDB client with a Micronaut application

Authors: Sergio del Amo

Micronaut Version: 4.6.3

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

You will use MongoDB for persistence.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=yaml,mongo-reactive,reactor,serialization-bson,serialization-jackson,graalvm \
    --build=maven \
    --lang=java \
    --test=junit
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add yaml, mongo-reactive, reactor, serialization-bson, serialization-jackson, and graalvm features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. POJO

Create Fruit POJO:

src/main/java/example/micronaut/Fruit.java
package example.micronaut;

import io.micronaut.core.annotation.Creator;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.serde.annotation.Serdeable;
import org.bson.codecs.pojo.annotations.BsonCreator;
import org.bson.codecs.pojo.annotations.BsonProperty;

import jakarta.validation.constraints.NotBlank;

@Serdeable (1)
public class Fruit {

    @NonNull
    @NotBlank (2)
    @BsonProperty("name") (3)
    private final String name;

    @Nullable
    @BsonProperty("description") (3)
    private final String description;

    public Fruit(@NonNull String name) {
        this(name, null);
    }

    @Creator (4)
    @BsonCreator(3)
    public Fruit(@NonNull @BsonProperty("name") String name,  (3)
                 @Nullable @BsonProperty("description") String description) {  (3)
        this.name = name;
        this.description = description;
    }

    @NonNull
    public String getName() {
        return name;
    }

    @Nullable
    public String getDescription() {
        return description;
    }
}
1 Declare the @Serdeable annotation at the type level in your source code to allow the type to be serialized or deserialized.
2 Use jakarta.validation.constraints Constraints to ensure the data matches your expectations.
3 Since the POJO does not have an empty constructor, use the annotations @BsonCreator and BsonProperty to define data conversion between BSON and POJO with the MongoDB Java driver. See POJOs without No-Argument Constructor.
4 Annotate with @Creator to provide a hint as to which constructor is the primary constructor.

4.2. Repository

Create a repository interface to encapsulate the CRUD actions for Fruit.

src/main/java/example/micronaut/FruitRepository.java
package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Mono;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;

public interface FruitRepository {

    @NonNull
    Publisher<Fruit> list();

    Mono<Boolean> save(@NonNull @NotNull @Valid Fruit fruit); (1)
}
1 Add @Valid to any method parameter which requires validation.

4.3. Controller

Create FruitController:

src/main/java/example/micronaut/FruitController.java
package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Mono;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;

import static io.micronaut.http.HttpStatus.CONFLICT;
import static io.micronaut.http.HttpStatus.CREATED;

@Controller("/fruits") (1)
class FruitController {

    private final FruitRepository fruitService;

    FruitController(FruitRepository fruitService) {  (2)
        this.fruitService = fruitService;
    }

    @Get (3)
    Publisher<Fruit> list() {
        return fruitService.list();
    }

    @Post (4)
    Mono<HttpStatus> save(@NonNull @NotNull @Valid Fruit fruit) { (5)
        return fruitService.save(fruit) (6)
                .map(added -> added ? CREATED : CONFLICT);
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /fruits.
2 Use constructor injection to inject a bean of type FruitRepository.
3 The @Get annotation maps the list method to an HTTP GET request on /fruits.
4 The @Post annotation maps the save method to an HTTP POST request on /fruits.
5 Add @Valid to any method parameter which requires validation.
6 Micronaut controller methods can return reactive types

4.4. Configuration

Create a configuration object to encapsulate the MongoDB database name and collection name.

src/main/java/example/micronaut/MongoDbConfiguration.java
package example.micronaut;

import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.naming.Named;

@ConfigurationProperties("db") (1)
public interface MongoDbConfiguration extends Named {

    @NonNull
    String getCollection();
}
1 The @ConfigurationProperties annotation takes the configuration prefix.

Define the values via configuration:

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.
src/main/resources/application.yml
db:
  name: 'fruit'
  collection: 'fruit'

4.5. MongoDB repository

Implement FruitRepository by using a MongoClient

src/main/java/example/micronaut/MongoDbFruitRepository.java
package example.micronaut;

import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoCollection;
import io.micronaut.core.annotation.NonNull;
import jakarta.inject.Singleton;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Mono;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;

@Singleton (1)
public class MongoDbFruitRepository implements FruitRepository {

    private final MongoDbConfiguration mongoConf;
    private final MongoClient mongoClient;

    public MongoDbFruitRepository(MongoDbConfiguration mongoConf,  (2)
                                  MongoClient mongoClient) {  (3)
        this.mongoConf = mongoConf;
        this.mongoClient = mongoClient;
    }

    @Override
    public Mono<Boolean> save(@NonNull @NotNull @Valid Fruit fruit) {
        return Mono.from(getCollection().insertOne(fruit)) (4)
                .map(insertOneResult -> true)
                .onErrorReturn(false);
    }

    @Override
    @NonNull
    public Publisher<Fruit> list() {
        return getCollection().find(); (4)
    }

    @NonNull
    private MongoCollection<Fruit> getCollection() {
        return mongoClient.getDatabase(mongoConf.getName())
                .getCollection(mongoConf.getCollection(), Fruit.class);
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Use constructor injection to inject a bean of type MongoDbConfiguration.
3 Use constructor injection to inject a bean of type MongoClient.
4 MongoClient methods return reactive sequences.

By using the feature mongo-reactive, the application includes the following dependency:

pom.xml
<dependency>
    <groupId>io.micronaut.mongodb</groupId>
    <artifactId>micronaut-mongo-reactive</artifactId>
    <scope>compile</scope>
</dependency>

This registers a non-blocking reactive streams MongoDB client with MongoClient, which you can inject in other Micronaut beans as illustrated in the above code sample.

4.6. Test

Add a Micronaut declarative HTTP Client to src/test to ease the testing of the application’s API.

src/test/java/example/micronaut/FruitClient.java
package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.client.annotation.Client;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import java.util.List;

@Client("/fruits")
public interface FruitClient {

    @Post
    @NonNull
    HttpStatus save(@NonNull @NotNull @Valid Fruit fruit);

    @NonNull
    @Get
    List<Fruit> findAll();
}

By using the feature mongo-sync, the application includes the following test dependencies:

pom.xml
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mongodb</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <scope>test</scope>
</dependency>

Test Resources will provide us with a MongoDB instance for local testing and execution.

Create a test:

src/test/java/example/micronaut/FruitControllerTest.java
package example.micronaut;

import io.micronaut.http.HttpStatus;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.Timeout;
import org.junit.jupiter.api.TestInstance;

import java.util.Collections;
import java.util.List;
import java.util.Map;

import static io.micronaut.http.HttpStatus.CREATED;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS;

@MicronautTest
@TestInstance(PER_CLASS)
public class FruitControllerTest {

    @Inject
    FruitClient fruitClient;

    @Test
    @Timeout(120)
    void fruitsEndpointInteractsWithMongo() {

        List<Fruit> fruits = fruitClient.findAll();
        assertTrue(fruits.isEmpty());

        HttpStatus status = fruitClient.save(new Fruit("banana"));
        assertEquals(CREATED, status);

        fruits = fruitClient.findAll();
        assertFalse(fruits.isEmpty());
        assertEquals("banana", fruits.get(0).getName());
        assertNull(fruits.get(0).getDescription());

        status = fruitClient.save(new Fruit("Apple", "Keeps the doctor away"));
        assertEquals(CREATED, status);

        fruits = fruitClient.findAll();
        assertTrue(fruits.stream().anyMatch(f -> "Keeps the doctor away".equals(f.getDescription())));
    }
}

5. Test Resources

When the application is started locally — either under test or by running the application — resolution of the property mongodb.uri is detected and the Test Resources service will start a local MongoDB docker container, and inject the properties required to use this as the datasource.

When running under production, you should replace this property with the location of your production MongoDB instance via an environment variable.

MONGODB_URI=mongodb://username:password@production-server:27017/databaseName

For more information, see the MongoDB section of the Test Resources documentation.

6. Testing the Application

To run the tests:

./mvnw test

7. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

curl -d '{"name":"Pear"}'
     -H "Content-Type: application/json"
     -X POST http://localhost:8080/fruits
curl -i localhost:8080/fruits
HTTP/1.1 200 OK
date: Wed, 15 Sep 2021 12:40:15 GMT
Content-Type: application/json
content-length: 110
connection: keep-alive

[{"name":"Pear"}]

8. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

8.1. GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 21
sdk install java 21.0.5-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 21
sdk install java 21.0.2-graalce

8.2. Native Executable Generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

It is possible to customize the name of the native executable or pass additional build arguments using the Maven plugin for GraalVM Native Image building. Declare the plugin as following:

pom.xml
<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.10.3</version>
    <configuration>
        <!-- <1> -->
        <imageName>mn-graalvm-application</imageName> (1)
        <buildArgs>
              <!-- <2> -->
          <buildArg>-Ob</buildArg>
        </buildArgs>
    </configuration>
</plugin>
1 The native executable name will now be mn-graalvm-application.
2 It is possible to pass extra build arguments to native-image. For example, -Ob enables the quick build mode.

Consume the endpoints exposed by the native executable with cURL:

curl -d '{"name":"Pear"}'
     -H "Content-Type: application/json"
     -X POST http://localhost:8080/fruits
curl -i localhost:8080/fruits
HTTP/1.1 200 OK
date: Wed, 15 Sep 2021 12:40:15 GMT
Content-Type: application/json
content-length: 110
connection: keep-alive

[{"name":"Pear"}]

9. Next Steps

Explore more features with Micronaut Guides.

10. Next Steps

Read more about the integration between the Micronaut framework and MongoDB.

11. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

12. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).