Groovy / Gradle

Micronaut MongoDB Synchronous

Learn how to use a blocking MongoClient with a Micronaut application

Sergio del Amo

On this guide

In this section

Getting Started

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

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

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=mongo-sync,serialization-bson,serialization-jackson \
    --build=gradle \
    --lang=groovy \
    --test=spock

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 mongo-sync, serialization-bson, and serialization-jackson 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.

POJO

Create a Fruit POJO:

groovy/src/main/groovy/example/micronaut/Fruit.groovy

package example.micronaut

import groovy.transform.CompileStatic
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

@CompileStatic
@Serdeable // 
class Fruit {

    @NonNull
    @NotBlank // 
    @BsonProperty('name') // 
    private final String name

    @Nullable
    @BsonProperty('description') // 
    private final String description

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

    @Creator // 
    @BsonCreator// 
    Fruit(@NonNull @BsonProperty('name') String name,  // 
          @Nullable @BsonProperty('description') String description) {  // 
        this.name = name
        this.description = description
    }

    @NonNull
    String getName() {
        name
    }

    @Nullable
    String getDescription() {
        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.

Repository

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

groovy/src/main/groovy/example/micronaut/FruitRepository.groovy

package example.micronaut

import io.micronaut.core.annotation.NonNull

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

interface FruitRepository {

    @NonNull
    List<Fruit> list()

    void save(@NonNull @NotNull @Valid Fruit fruit) // 
}

1	Add `@Valid` to any method parameter which requires validation.

Controller

Create FruitController:

groovy/src/main/groovy/example/micronaut/FruitController.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.core.annotation.NonNull
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Status
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

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

import static io.micronaut.http.HttpStatus.CREATED

@CompileStatic
@Controller('/fruits') // 
@ExecuteOn(TaskExecutors.BLOCKING) // 
class FruitController {

    private final FruitRepository fruitService

    FruitController(FruitRepository fruitService) {  // 
        this.fruitService = fruitService
    }

    @Get// 
    List<Fruit> list() {
        fruitService.list()
    }

    @Post // 
    @Status(CREATED) // 
    void save(@NonNull @NotNull @Valid Fruit fruit) { // 
        fruitService.save(fruit)
    }
}

1	The class is defined as a controller with the @Controller annotation mapped to the path `/fruits`.
2	It is critical that any blocking I/O operations (such as fetching the data from the database) are offloaded to a separate thread pool that does not block the Event loop.
3	Use constructor injection to inject a bean of type `FruitRepository`.
4	The @Get annotation maps the `list` method to an HTTP GET request on `/fruits`.
5	The @Post annotation maps the `save` method to an HTTP POST request on `/fruits`.
6	You can return `void` in your controller’s method and specify the HTTP status code via the `@Status` annotation.
7	Add `@Valid` to any method parameter which requires validation.

Configuration

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

groovy/src/main/groovy/example/micronaut/MongoDbConfiguration.groovy

package example.micronaut

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

@ConfigurationProperties('db') // 
interface MongoDbConfiguration extends Named {

    @NonNull
    String getCollection()
}

1	The `@ConfigurationProperties` annotation takes the configuration prefix.

Define the values via configuration:

src/main/resources/application.properties

db.name=fruit
db.collection=fruit

MongoDB repository

Implement FruitRepository by using a MongoDbClient.

groovy/src/main/groovy/example/micronaut/MongoDbFruitRepository.groovy

package example.micronaut

import com.mongodb.client.MongoClient
import com.mongodb.client.MongoCollection
import io.micronaut.core.annotation.NonNull
import jakarta.inject.Singleton

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

@Singleton // 
class MongoDbFruitRepository implements FruitRepository {

    private final MongoDbConfiguration mongoConf
    private final MongoClient mongoClient

    MongoDbFruitRepository(MongoDbConfiguration mongoConf,  // 
                           MongoClient mongoClient) {  // 
        this.mongoConf = mongoConf
        this.mongoClient = mongoClient
    }

    @Override
    void save(@NonNull @NotNull @Valid Fruit fruit) {
        collection.insertOne(fruit)
    }

    @Override
    @NonNull
    List<Fruit> list() {
        collection.find().into([])
    }

    @NonNull
    private MongoCollection<Fruit> getCollection() {
        return mongoClient.getDatabase(mongoConf.name)
                .getCollection(mongoConf.collection, Fruit)
    }
}

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 `MongoDbClient`.

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

build.gradle

implementation("io.micronaut.mongodb:micronaut-mongo-sync")

This registers a blocking MongoClient, which you can inject in other Micronaut beans as illustrated in the above code sample.

Test

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

groovy/src/test/groovy/example/micronaut/FruitClient.groovy

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

@Client('/fruits')
interface FruitClient {

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

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

By using Test Resources, the application includes the following test dependencies:

build.gradle

testImplementation("org.testcontainers:testcontainers-junit-jupiter")
testImplementation("org.testcontainers:testcontainers-mongodb")
testImplementation("org.testcontainers:testcontainers")

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

Create a test:

groovy/src/test/groovy/example/micronaut/FruitControllerSpec.groovy

package example.micronaut

import io.micronaut.http.HttpStatus
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification

import static io.micronaut.http.HttpStatus.CREATED

@MicronautTest
class FruitControllerSpec extends Specification {

    @Inject
    FruitClient fruitClient

    void fruitsEndpointInteractsWithMongo() {

        when:
        List<Fruit> fruits = fruitClient.findAll()

        then:
        !fruits

        when:
        HttpStatus status = fruitClient.save(new Fruit('banana'))

        then:
        CREATED == status

        when:
        fruits = fruitClient.findAll()

        then:
        fruits
        'banana' == fruits[0].name
        null == fruits[0].description

        when:
        status = fruitClient.save(new Fruit('Apple', 'Keeps the doctor away'))

        then:
        CREATED == status

        when:
        fruits = fruitClient.findAll()

        then:
        fruits.find { it.description == 'Keeps the doctor away' }
    }
}

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"}]

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.

Next Steps

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