Java / Gradle

Access a MongoDB database asynchronously with Micronaut Data MongoDB and Reactive Streams

Learn how to access a MongoDB database asynchronously with Micronaut Data.

Tim Yates

On this guide

In this section

Getting Started

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

You will use MongoDB for persistence.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately
Docker installed to run MongoDB and to run tests using Testcontainers.

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.

Download and unzip the source

Writing the Application

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

mn create-app example.micronaut.micronautguide \
    --features=data-mongodb-reactive,reactor \
    --build=gradle \
    --lang=java \
    --test=junit

Note	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 data-mongodb-reactive, and reactor features.

Note	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.

Dependencies

In this guide, we use the MongoDB Reactive driver.

The data-mongodb-reactive feature adds the following dependencies:

build.gradle

annotationProcessor("io.micronaut.data:micronaut-data-document-processor")
implementation("io.micronaut.data:micronaut-data-mongodb")
runtimeOnly("org.mongodb:mongodb-driver-reactivestreams")
implementation("org.mongodb:mongodb-driver-reactivestreams")

POJO

Create a Fruit POJO:

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

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.data.annotation.GeneratedValue;
import io.micronaut.data.annotation.Id;
import io.micronaut.data.annotation.MappedEntity;

import jakarta.validation.constraints.NotBlank;

@MappedEntity // 
public class Fruit {

    @Id // 
    @GeneratedValue
    private String id;

    @NonNull
    @NotBlank // 
    private final String name;

    @Nullable
    private String description;

    public Fruit(@NonNull String name, @Nullable String description) {
        this.name = name;
        this.description = description;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

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

    @Nullable
    public String getDescription() {
        return description;
    }

    public void setDescription(@Nullable String description) {
        this.description = description;
    }
}

1	Annotate the class with `@MappedEntity` to map the class to the table defined in the schema.
2	Specifies the ID of an entity
3	Use `jakarta.validation.constraints` Constraints to ensure the data matches your expectations.

Repository

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

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

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.data.mongodb.annotation.MongoRepository;
import io.micronaut.data.repository.reactive.ReactiveStreamsCrudRepository;
import org.reactivestreams.Publisher;

import java.util.List;

@MongoRepository // 
public interface FruitRepository extends ReactiveStreamsCrudRepository<Fruit, String> { // 

    @NonNull
    Publisher<Fruit> findByNameInList(@NonNull List<String> names); // 
}

1	Annotate with `@MongoRepository`.
2	Extend `ReactiveStreamsCrudRepository` for asynchronous database access.
3	Add a finder for finding fruit by a list of names.

Service

Create a service FruitService as an API to interact with the Fruit repository. This will allow you to keep business logic out of the controller, and to test the controller later without interacting with a real database.

java/src/main/java/example/micronaut/FruitService.java

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import org.reactivestreams.Publisher;

import java.util.List;

interface FruitService {

    Publisher<Fruit> list();

    Publisher<Fruit> save(Fruit fruit);

    Publisher<Fruit> find(@NonNull String id);

    Publisher<Fruit> findByNameInList(List<String> name);
}

And then create a default implementation of this service.

java/src/main/java/example/micronaut/DefaultFruitService.java

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import jakarta.inject.Singleton;
import org.reactivestreams.Publisher;

import java.util.List;

@Singleton // 
class DefaultFruitService implements FruitService {

    private final FruitRepository fruitRepository;

    public DefaultFruitService(FruitRepository fruitRepository) {
        this.fruitRepository = fruitRepository;
    }

    public Publisher<Fruit> list() {
        return fruitRepository.findAll();
    }

    public Publisher<Fruit> save(Fruit fruit) {
        if (fruit.getId() == null) {
            return fruitRepository.save(fruit);
        } else {
            return fruitRepository.update(fruit);
        }
    }

    public Publisher<Fruit> find(@NonNull String id) {
        return fruitRepository.findById(id);
    }

    public Publisher<Fruit> findByNameInList(List<String> name) {
        return fruitRepository.findByNameInList(name);
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.

Controller

Create FruitController:

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

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.async.annotation.SingleResult;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Put;
import io.micronaut.http.annotation.QueryValue;
import io.micronaut.http.annotation.Status;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import org.reactivestreams.Publisher;

import java.util.List;

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

    private final FruitService fruitService;

    FruitController(FruitService fruitService) {  // 
        this.fruitService = fruitService;
    }

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

    @Post // 
    @Status(HttpStatus.CREATED) // 
    @SingleResult
    Publisher<Fruit> save(@NonNull @NotNull @Valid Fruit fruit) { // 
        return fruitService.save(fruit);
    }

    @Put
    @SingleResult
    Publisher<Fruit> update(@NonNull @NotNull @Valid Fruit fruit) {
        return fruitService.save(fruit);
    }

    @Get("/{id}") // 
    Publisher<Fruit> find(@PathVariable String id) {
        return fruitService.find(id);
    }

    @Get("/q") // 
    Publisher<Fruit> query(@QueryValue @NotNull List<String> names) { // 
        return fruitService.findByNameInList(names);
    }
}

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 `FruitService`.
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	You can specify the HTTP status code via the `@Status` annotation.
6	Add `@Valid` to any method parameter which requires validation.
7	The @Get annotation maps the `find` method to an HTTP GET request on `/fruits/{id}`.
8	The @Get annotation maps the `findByNameInList` method to an HTTP GET request on `/fruits/q`.
9	Bind a list of Strings to the query parameter `names`

Test Client

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

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

package example.micronaut;

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Put;
import io.micronaut.http.annotation.QueryValue;
import io.micronaut.http.client.annotation.Client;
import jakarta.validation.constraints.NotNull;

import java.util.List;
import java.util.Optional;

@Client("/fruits")
interface FruitClient {

    @Get
    Iterable<Fruit> list();

    @Get("/{id}")
    Optional<Fruit> find(@PathVariable String id);

    @Get("/q")
    Iterable<Fruit> query(@QueryValue @NotNull List<String> names);

    @Post
    HttpResponse<Fruit> save(Fruit fruit);

    @Put
    Fruit update(Fruit fruit);
}

Then create a test that verifies the validation of the Fruit entity when we create a new entity via POST:

java/src/test/java/example/micronaut/FruitValidationControllerTest.java

package example.micronaut;

import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.http.client.exceptions.HttpClientResponseException;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

@MicronautTest(transactional = false) // 
class FruitValidationControllerTest {

    @Inject
    @Client("/")
    HttpClient httpClient;

    @Test
    void fruitIsValidated() {
        HttpClientResponseException exception = assertThrows(
                HttpClientResponseException.class,
                () -> httpClient.toBlocking().exchange(HttpRequest.POST("/fruits", new Fruit("", "")))
        );

        assertEquals(HttpStatus.BAD_REQUEST, exception.getStatus());
    }
}

1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. By default, each @Test method will be wrapped in a transaction that will be rolled back when the test finishes. This behaviour is is changed by setting transaction to false.

Note	Transaction mode is not supported when the synchronous transaction manager is created using Reactive transaction manager!

Create a test that checks the controller works against a real MongoDB database:

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

package example.micronaut;

import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import reactor.core.publisher.Flux;

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;

@MicronautTest(transactional = false) // 
class FruitControllerTest {

    @Inject
    FruitClient fruitClient;

    @Inject
    FruitRepository fruitRepository;

    @AfterEach // 
    void cleanup() {
        Flux.from(fruitRepository.deleteAll()).blockFirst();
    }

    @Test
    void emptyDatabaseContainsNoFruit() {
        assertEquals(0, StreamSupport.stream(fruitClient.list().spliterator(), false).count());
    }

    @Test
    void testInteractionWithTheController() {
        HttpResponse<Fruit> response = fruitClient.save(new Fruit("banana", null));
        assertEquals(HttpStatus.CREATED, response.getStatus());
        Fruit banana = response.getBody().get();

        Iterable<Fruit> fruits = fruitClient.list();
        List<Fruit> fruitList = StreamSupport.stream(fruits.spliterator(), false).toList();
        assertEquals(1, fruitList.size());
        assertEquals(banana.getName(), fruitList.get(0).getName());
        assertNull(fruitList.get(0).getDescription());

        response = fruitClient.save(new Fruit("apple", "Keeps the doctor away"));
        assertEquals(HttpStatus.CREATED, response.getStatus());

        fruits = fruitClient.list();
        assertTrue(StreamSupport.stream(fruits.spliterator(), false)
                .anyMatch(f -> "Keeps the doctor away".equals(f.getDescription())));

        banana.setDescription("Yellow and curved");
        fruitClient.update(banana);

        fruits = fruitClient.list();

        assertEquals(
                Stream.of("Keeps the doctor away", "Yellow and curved").collect(Collectors.toSet()),
                StreamSupport.stream(fruits.spliterator(), false)
                        .map(Fruit::getDescription)
                        .collect(Collectors.toSet())
        );
    }

    @Test
    void testSearchWorksAsExpected() {
        fruitClient.save(new Fruit("apple", "Keeps the doctor away"));
        fruitClient.save(new Fruit("pineapple", "Delicious"));
        fruitClient.save(new Fruit("lemon", "Lemonentary my dear Dr Watson"));

        Iterable<Fruit> fruit = fruitClient.query(Arrays.asList("apple", "pineapple"));

        assertTrue(StreamSupport.stream(fruit.spliterator(), false)
                .allMatch(f -> f.getName().equals("apple") || f.getName().equals("pineapple")));
    }
}

1	Annotate the class with `@MicronautTest` so the Micronaut framework will initialize the application context and the embedded server. By default, each `@Test` method will be wrapped in a transaction that will be rolled back when the test finishes. This behaviour is is changed by setting `transaction` to `false`.
2	Clean up the database after each test method execution.

And finally, create a test which uses a replacement FruitService to test the controller without touching the database:

java/src/test/java/example/micronaut/ControllerIsolationTest.java

package example.micronaut;

import io.micronaut.context.annotation.Property;
import io.micronaut.context.annotation.Replaces;
import io.micronaut.context.annotation.Requires;
import io.micronaut.core.type.Argument;
import io.micronaut.http.HttpHeaders;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.MediaType;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import jakarta.inject.Singleton;
import jakarta.validation.constraints.NotNull;
import org.junit.jupiter.api.Test;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.List;
import java.util.stream.Collectors;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@MicronautTest(transactional = false) // 
@Property(name = "spec.name", value = "controller-isolation")
class ControllerIsolationTest {

    @Inject
    @Client("/")
    HttpClient httpClient;

    @Test
    void checkSerialization() {
        MutableHttpRequest<Object> get = HttpRequest.GET("/fruits");
        HttpResponse<List<Fruit>> response = httpClient.toBlocking().exchange(get, Argument.listOf(Fruit.class));

        assertEquals(HttpStatus.OK, response.getStatus());
        assertEquals(MediaType.APPLICATION_JSON, response.getHeaders().get(HttpHeaders.CONTENT_TYPE));
        assertTrue(response.getBody().isPresent());

        String all = response.getBody().get().stream().map(f -> f.getName() + ":" + f.getDescription()).collect(Collectors.joining(","));
        assertEquals("apple:red,banana:yellow", all);
    }

    @Singleton
    @Replaces(DefaultFruitService.class)
    @Requires(property = "spec.name", value = "controller-isolation")
    static class MockService implements FruitService {

        @Override
        public Publisher<Fruit> list() {
            return Flux.just(
                    new Fruit("apple", "red"),
                    new Fruit("banana", "yellow")
            );
        }

        @Override
        public Publisher<Fruit> save(Fruit fruit) {
            return Mono.just(fruit);
        }

        @Override
        public Publisher<Fruit> find(@NotNull String id) {
            return Mono.empty();
        }

        @Override
        public Publisher<Fruit> findByNameInList(List<String> name) {
            return Flux.empty();
        }
    }
}

Test Resources

When the application is started locally, either under test or while running locally, 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.

Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

Running the Application

To run the application, use the ./gradlew 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"}]

Next Steps

Explore more features with Micronaut Guides.

Read more about the integration between Micronaut Data and MongoDB.

Help with the Micronaut Framework

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

License

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