To be even more specific- we will work with an application that exposes a REST API and connects to MongoDB. If you would like to learn how to do that step-by-step, then you can check out my other article. (But don’t worry, we will see its code snippets in this tutorial, too).

For testing, we’re going to use JUnit 5, MockK, REST Assured, as well as the @MicronautTest and Micronaut Test Resources.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Micronaut Project Overview

Let’s start everything by checking the project we will test today. Of course, we will focus on the most important parts, and for the full source code, I invite you to this GitHub repository.

Application Properties

In our project, we introduce 3 application properties files:

// application.properties
micronaut.application.name=micronaut-testing

// application-mongo.properties
mongodb.uri=mongodb://localhost:27017/example

// application-test.properties
mongodb.package-names=com.codersee.model

The application name is the default property inserted when generating a new project.

Nevertheless, the two remaining are created on purpose. With their names- *mongo, *test– we instruct Micronaut that it should consider them only when mongo and test profiles are active.

But why this way? Well, to avoid two issues.

MongoDB Connection Issues with Micronaut Test Resources

So, let’s start everything by explaining why we don’t put the Mongo URI inside the main properties.

Well, when we use the Micronaut Test Resources, MongoDB support will start a MongoDB container and provide the value of the mongodb.uri property.

Nevertheless, this won’t happen when we explicitly set the URI in the application properties. And that’s why we want to make this setting available only when we set the environment to mongo.

CodecCacheKey Issue

Additionally, if we don’t specify explicitly the package name, where our model classes live, we’re going to end up with the following issue when running our Micronaut tests:

[io-executor-thread-1] ERROR i.m.http.server.RouteExecutor - Unexpected error occurred: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
  at org.bson.internal.ProvidersCodecRegistry.lambda$get$0(ProvidersCodecRegistry.java:87)
  at java.base/java.util.Optional.orElseGet(Optional.java:364)
  at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:80)
  at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:50)
  at com.mongodb.internal.operation.Operations.createFindOperation(Operations.java:188)
...

To me, looks like a bug. But thankfully, we can easily avoid that by putting that in the application-test.properties (which is used in tests by default).

Models

Following, we introduce a bunch of models:

// Address.kt: 

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Serializable
@Serdeable.Deserializable
data class Address(
  val street: String,
  val city: String,
  val code: Int
)

// AppUser.kt:

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

@MappedEntity
data class AppUser(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val firstName: String,
  val lastName: String,
  val email: String,
  val address: Address
)

// AppUserRequest.kt: 

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Deserializable
data class AppUserRequest(
  val firstName: String,
  val lastName: String,
  val email: String,
  val street: String,
  val city: String,
  val code: Int
)

// SearchRequest.kt:

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Deserializable
data class SearchRequest(val name: String)

Those classes are either used to persist/retrieve data from MongoDB or when deserializing JSON payloads into the objects.

Repository

Following, we have a repository layer responsible for communicating with our storage:

// AppUserRepository.kt: 

import com.codersee.model.AppUser
import io.micronaut.data.mongodb.annotation.MongoFindQuery
import io.micronaut.data.mongodb.annotation.MongoRepository
import io.micronaut.data.repository.CrudRepository

@MongoRepository
interface AppUserRepository : CrudRepository<AppUser, String> {

  fun findByFirstNameEquals(firstName: String): List<AppUser>

  @MongoFindQuery("{ firstName: { \$regex: :name}}")
  fun findByFirstNameLike(name: String): List<AppUser>
}

Service

Nextly, the service layer, where we inject the repository and encapsulate its methods:

// AppUserService.kt:

import com.codersee.model.Address
import com.codersee.model.AppUser
import com.codersee.model.AppUserRequest
import com.codersee.repository.AppUserRepository
import io.micronaut.http.HttpStatus
import io.micronaut.http.exceptions.HttpStatusException
import jakarta.inject.Singleton

@Singleton
class AppUserService(
  private val appUserRepository: AppUserRepository
) {

  fun create(userRequest: AppUserRequest): AppUser =
    appUserRepository.save(
      userRequest.toAppUserEntity()
    )

  fun findAll(): List<AppUser> =
    appUserRepository
      .findAll()
      .toList()

  fun findById(id: String): AppUser =
    appUserRepository.findById(id)
      .orElseThrow { HttpStatusException(HttpStatus.NOT_FOUND, "User with id: $id was not found.") }

  fun update(id: String, updateRequest: AppUserRequest): AppUser {
    val foundUser = findById(id)

    val updatedEntity =
      updateRequest
        .toAppUserEntity()
        .copy(id = foundUser.id)

    return appUserRepository.update(updatedEntity)
  }

  fun deleteById(id: String) {
    val foundUser = findById(id)

    appUserRepository.delete(foundUser)
  }

  fun findByNameLike(name: String): List<AppUser> =
    appUserRepository
      .findByFirstNameLike(name)

  private fun AppUserRequest.toAppUserEntity(): AppUser {
    val address = Address(
      street = this.street,
      city = this.city,
      code = this.code
    )

    return AppUser(
      id = null,
      firstName = this.firstName,
      lastName = this.lastName,
      email = this.email,
      address = address
    )
  }
}

Controller

And lastly, the place where we expose our REST endpoints:

// AppUserController.kt: 

import com.codersee.model.AppUserRequest
import com.codersee.service.AppUserService
import com.codersee.model.SearchRequest
import com.codersee.model.AppUser
import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/users")
@ExecuteOn(TaskExecutors.IO)
class AppUserController(
  private val appUserService: AppUserService
) {

  @Get
  fun findAllUsers(): List<AppUser> =
    appUserService.findAll()

  @Get("/{id}")
  fun findById(@PathVariable id: String): AppUser =
    appUserService.findById(id)

  @Post
  @Status(HttpStatus.CREATED)
  fun createUser(@Body request: AppUserRequest): AppUser =
    appUserService.create(request)

  @Post("/search")
  fun searchUsers(@Body searchRequest: SearchRequest): List<AppUser> =
    appUserService.findByNameLike(
      name = searchRequest.name
    )

  @Put("/{id}")
  fun updateById(
    @PathVariable id: String,
    @Body request: AppUserRequest
  ): AppUser =
    appUserService.update(id, request)

  @Delete("/{id}")
  @Status(HttpStatus.NO_CONTENT)
  fun deleteById(@PathVariable id: String) =
    appUserService.deleteById(id)
}

Simple Kotlin Testing in Micronaut

Excellent. At this point, we know what exactly we are going to test.

And as the first approach we’re going to see will be a plain, old unit test.

Why?

Because at the end of the day, that’s what we will be dealing with most of the time.

So with that said, let’s take a look at the example test:

  import com.codersee.repository.AppUserRepository
import io.mockk.every
import io.mockk.mockk
import io.mockk.verify
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test

class AppUserServiceTest {

  private val appUserRepository = mockk<AppUserRepository>()

  private val appUserService = AppUserService(appUserRepository)

  @Test
  fun `should return empty user list`() {
    every {
      appUserRepository.findAll()
    } returns emptyList()

    val result = appUserService.findAll()

    assertTrue(result.isEmpty())

    verify(exactly = 1) { appUserRepository.findAll() }
  }
}

As we can see above, we simply mock (with MockK) the AppUserRepository and inject it into the AppUserService instance.

Then, we specify that all invocations of the findAll method must return the empty list (with every).

Lastly, we assert that the findAll method from our service returns an empty list (assertTrue) and that the findAll method from the repository was invoked only once (verify).

Nevertheless, we’re not going to spend too much here right now as this tutorial focuses on Micronaut testing in Kotlin. If you are interested in learning more about these tools, then let me know in the comments section 🙂

Integration Testing with @MicronautTest

With all of that done, let’s see how the Micronaut framework helps us with testing and a few interesting cases that will help us in real life.

What is a @MicronautTest?

Let’s start everything by explaining what exactly is the @MicronautTest.

In simple words, it’s an annotation that we can put on the test class to mark it a Micronaut test (no sh… Sherlock 🙂 :

import io.micronaut.test.extensions.junit5.annotation.MicronautTest

@MicronautTest
class SomeTest {
  // tests
}

In practice, it means that when we run a test with that annotation, it will run a real application. It will use internal Micronaut features with no mocking. So at this point, we can clearly see that this will be the right solution for integration testing.

Moreover, this annotation can be used not only with JUnit 5, but also with Spock, Kotest, and Kotest 5.

@MicronautTest Configuration Options

The @MicronautTest allows us to configure a few properties, like the environments we want to run our test with, the packages to scan, or whether the automatic transaction wrapping should be enabled, or not:

import io.micronaut.test.extensions.junit5.annotation.MicronautTest

@MicronautTest(
  environments = ["env-1, env-2"],
  packages = ["com.codersee.somepackage"],
  transactional = false
)
class SomeTest {
  // tests
}

For the full list of options, I highly encourage you to check out the docs (we can do that for instance in IntelliJ IDEA by clicking on the annotation with the left mouse button when we keep the left ctrl pressed).

What Are Micronaut Test Resources?

At the beginning of this tutorial, I mentioned the Micronaut Test Resources and I would like to make sure that we are on the same page with them.

So basically, Micronaute Test Resources integrates seamlessly with Testcontainers to provide throwaway containers for testing. But, we need to remember that Testcontainers require Docker-API compatible container runtime (in simple words- either Docker installed locally, or the Testcontainers Cloud).

In our case, we would like to do integration tests that require MongoDB. We could make use of the real database (which sometimes may be the case for you), provide some H2 database (not the best approach), or integrate Testcontainers. Thankfully, we don’t need to do that and the only thing we need is the appropriate import in our project:

plugins {
    id("io.micronaut.test-resources") version "4.2.1"
}

As a reminder, I want to emphasize that test resources will be used only when the datasources.default.url is missing. (and that’s why we removed the URI for MongoDB from tests).

Integration Tests With REST Assured

With all of that said, let’s combine everything together and test our Kotlin Micronaut application with JUnit 5 and REST Assured.

To do so, we must remember to add the necessary import:

testImplementation("io.micronaut.test:micronaut-test-rest-assured")

Verify Status Codes and Headers

Let’s start with a simple request to the GET /users endpoint:

@MicronautTest
class AppUserControllerTestWithoutMocking {

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    spec
      .`when`()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }

}

As I mentioned previously- by default, with @MicronautTest the real application is started. Moreover, nothing here is mocked, so the Mongo test container delivered by the Micronaut Test Resources is used.

Thanks to the dedicated module we added, we can inject the RequestSpecification into our tests and easily validate our endpoint.

In this case, we perform a GET request and verify that the response status code is 200 OK and the response Content-Type header value is application/json.

Verify 404 Not Found

Similarly, we can verify that no entry is present in the database:

@Test
fun `should return 404 Not Found on GET user by ID`(spec: RequestSpecification) {
  spec
    .`when`()
    .get("/users/123123123123123123121231")
    .then()
    .statusCode(404)
}

This test will be also good proof that entries inserted to MongoDB in other tests do not affect other tests.

Extract and JSON Array in REST Assured

Nextly, let’s take a look at the more complicated example:

@Test
fun `should create a user`(spec: RequestSpecification) {
  val request = AppUserRequest(
    firstName = "Piotr",
    lastName = "Wolak",
    email = "contact@codersee.com",
    street = "Street",
    city = "City",
    code = 123,
  )

  spec
    .`when`()
    .contentType(ContentType.JSON)
    .body(request)
    .post("/users")
    .then()
    .statusCode(201)

  val list = spec
    .`when`()
    .get("/users")
    .then()
    .statusCode(200)
    .body("size()", `is`(1))
    .extract()
    .`as`(object : TypeRef<List<AppUser>>() {})

  assertEquals(1, list.size)

  val createdUser = list.first()

  assertEquals(request.firstName, createdUser.firstName)
  assertEquals(request.street, createdUser.address.street)
}

This time, we do a bunch of more interesting things.

Firstly, we make the POST request with a request body and verify that 201 Creates is returned.

After that, we call the GET /users endpoint to get a list of users. When we get the response, we verify that the JSON array size is equal to 1 (with the .body("size()", is(1)) call). Lastly, we make use of the extract().`as` to convert the payload into the List of AppUser instances. Thanks to that we can easily perform assertions with JUnit 5 functions.

Add Kotlin Utils For REST Assured

As you probably know, when and as are keywords in Kotlin and that’s why we had to use backticks (“).

And to make our lives easier, let’s add the util package in test and create the TestUtil.kt:

import io.restassured.common.mapper.TypeRef
import io.restassured.response.ValidatableResponse
import io.restassured.specification.RequestSpecification


fun RequestSpecification.whenever(): RequestSpecification {
  return this.`when`()
}

fun <T> ValidatableResponse.extractAs(clazz: Class<T>) =
  this.extract()
    .`as`(clazz)

fun <T> ValidatableResponse.extractAs(typeRef: TypeRef<T>) =
  this.extract()
    .`as`(typeRef)

As a result, from now on we can simply use the whenever() instead of `when`() and extractAs() instead of extract().`as`().

Reference The Server / Context

As the next step, let’s take a look at how to reference the server or current application context:

@MicronautTest
class InjectingExample{

  @Inject
  private lateinit var context: ApplicationContext

  @Inject
  private lateinit var server: EmbeddedServer

  // tests
}

Sometimes it can be useful, and as we can see, we can simply inject them using the @Inject annotation.

Conditionally Run Tests

After that, let’s see how we can skip tests execution.

Why would we need that?

Well, integration tests sometimes can take a lot of time, and the bigger our project becomes, the bigger the chance they become annoying. And because of that, generally, it’s a good approach to somehow separate them from the faster unit tests.

When testing in Micronaut, we can easily achieve that using the @Requires annotation:

import io.micronaut.context.annotation.Requires
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test

@MicronautTest
@Requires(env = ["integration-test"])
class SomeIntegrationTest {

  @Test
  fun `should perform integration test`() {
    assertTrue(false)
  }

}

The @MicronautTest annotation turns tests into beans. And that’s why we can use the @Requires, just like we would do with a “standard” bean.

As a result, tests inside the SomeIntegrationTest will run only, when the integration-test the environment is active. (And we can set that for example by setting the environment variable- MICRONAUT_ENVIRONMENTS=integration-test).

Testing Micronaut With MockK Mocks

As the last thing in our tutorial about testing Micronaut with Kotlin, let’s take a look at how we can mock things using the MockK.

Could we use Mockito? Yes. However, I find MockK better for Kotlin (DSLs <3 ).

In order to mock a bean in Micronaut, the only thing we need to do is annotate the method/inner class with the @MockBean annotation:

@MicronautTest
class AppUserControllerTestWithMocking {

  private val repo: AppUserRepository = mockk<AppUserRepository>()

  @MockBean(AppUserRepository::class)
  fun appUserRepository(): AppUserRepository = repo
}

As we can see, we introduce the AppUserRepository mock as the repo property, so that later, we will be able to refer to it easily in our test cases. Additionally, we add the function annotated with @MockBean, thus informing Micronaut that the AppUserRepository is the type we want to replace with our mock.

Moreover, thanks to this approach this mock will be limited only to tests defined in this class. So we can “rest assured” (hue hue) it won’t interfere with other classes.

As a result, our tests will look, as follows:

@MicronautTest
class AppUserControllerTestWithMocking {

  private val repo: AppUserRepository = mockk<AppUserRepository>()

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    every {
      repo.findAll()
    } returns emptyList()

    spec
      .whenever()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }

  @Test
  fun `should return user by ID`(spec: RequestSpecification) {
    val foundUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.findById("123")
    } returns Optional.of(foundUser)

    spec
      .whenever()
      .get("/users/123")
      .then()
      .statusCode(200)
      .body("id", equalTo("123"))
      .body("firstName", equalTo("Piotr"))
      .body("address.street", equalTo("street"))
      .body("address.code", equalTo(123))
  }

  @Test
  fun `should return user by ID and verify with extract`(spec: RequestSpecification) {
    val foundUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.findById("123")
    } returns Optional.of(foundUser)

    val extracted = spec
      .whenever()
      .get("/users/123")
      .then()
      .statusCode(200)
      .extractAs(AppUser::class.java)

    assertEquals(foundUser, extracted)
  }

  @Test
  fun `should create a user`(spec: RequestSpecification) {
    val request = AppUserRequest(
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      street = "Street",
      city = "City",
      code = 123,
    )

    val createdUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.save(any())
    } returns createdUser

    val extracted = spec
      .whenever()
      .contentType(ContentType.JSON)
      .body(request)
      .post("/users")
      .then()
      .statusCode(201)
      .extractAs(AppUser::class.java)

    assertEquals(createdUser, extracted)
  }

  @MockBean(AppUserRepository::class)
  fun appUserRepository(): AppUserRepository = repo
}

Summary

And that’s all for this tutorial on how to perform testing in Micronaut with Kotlin.

Together, we’ve discovered a bunch of interesting things that I hope will be useful in your projects.

If you would like to see the codebase for this tutorial, then check out this GitHub repository. Or, if you are interested in learning more about Micronaut, then check out my other posts.

Let me know your thoughts in the comments section below! 🙂

The post Testing Micronaut Application in Kotlin appeared first on Codersee blog- Kotlin on the backend.

In this short article, I will show you how to fix this issue based on the example project.

Trigger The CodecCacheKey in Micronaut Test

Before I show you how to fix this issue, let me quickly introduce you to how I trigger the CodecCacheKey issue when writing tests in Micronaut. (If you are interested in the whole project, check this article about Micronaut with MongoDB).

So firstly, I created a simple AppUser data class:

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

@MappedEntity
data class AppUser(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val firstName: String,
  val lastName: String,
  val email: String,
  val address: Address
)

Nothing spectacular. Just a simple class with a few annotations necessary to work with MongoDB and generate identifiers automatically.

As the next step, I added the repository, which looked, as follows:

@MongoRepository
interface AppUserRepository : CrudRepository<AppUser, String> {
 
  // few methods 
}

And all of that together with other classes that are not important in this tutorial, created a structure, like this:

So, lastly, I added a simple test with @MicronautTest, JUnit 5, and REST Assured to test whether my REST endpoint returns users from the Mongo database:

@MicronautTest
class AppUserControllerTestWithoutMocking {

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    spec
      .`when`()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }
}

As a result, instead of the beautiful, green icon indicating that everything is fine, I got the following:

[io-executor-thread-1] ERROR i.m.http.server.RouteExecutor - Unexpected error occurred: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
	at org.bson.internal.ProvidersCodecRegistry.lambda$get$0(ProvidersCodecRegistry.java:87)
	at java.base/java.util.Optional.orElseGet(Optional.java:364)
	at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:80)
	at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:50)
	at com.mongodb.internal.operation.Operations.createFindOperation(Operations.java:188)
...

Moreover, when I ran the application manually and tested using a real MongoDB instance, everything worked fine.

How To Fix CodecCacheKey Issue?

In order to fix the issue, I created a new file- called application-test.properties in the resources directory and put the following:

mongodb.package-names=com.codersee.model

But what exactly does it do?

Well, firstly, the application-test name of the file instructs the Micronaut framework to use this property file only when running tests.

Secondly, with the mongodb.package-names, I set package names to allow for POJOs. And that’s why I put the com.codersee.model only.

And voila, that’s all 🙂

Summary

And basically, that’s all for this short tutorial on how to fix the issue with CodecCacheKey in Micronaut.

Thank you for being here, and if you would like to learn more about the framework, then check out other posts from the Micronaut category.

If you would like to see the codebase for this tutorial, please refer to my GitHub repository.

The post Fix “Can’t find a codec for CodecCacheKey” in Micronaut appeared first on Codersee blog- Kotlin on the backend.

If you would like to learn:

• what exactly the Micronaut Framework is and what problems can you solve with it?
• how to create REST API using Micronaut and Kotlin programming language?
• how to set up a MongoDB instance with Docker and view the data with MongoDB Compass?
• and furthermore, how to set up all of the above step-by-step?

Then the Micronaut with Kotlin and MongoDB video tutorial will help you with all of the above. 12 free videos with around 56 minutes of the condensed knowledge are a great way to start your journey with the Micronaut framework.

As always, you can find it entirely for free on this blog, by simply clicking the Video Tutorials tab in the header, or by navigating to it with this, direct link.

Alternatively, you can find it on the YouTube platform as a playlist right here, but right there I cannot guarantee that you won’t see the ads, or that everything will be displayed in the correct order.

One more thing…

Finally, I just wanted to thank you for being a part of the Codersee community and ask you about one thing: I would be forever thankful if you share your feedback with me. Of course, regardless of whether you enjoy the course or you think it’s just a piece of s**t. I would love to hear your thoughts and how could I improve my content to better suit your needs. You can do it wherever you want: by using the contact form, using a comments section below, or even on YouTube.

Thank you for your time and have a great week!

The post Micronaut With Kotlin and MongoDB Video Tutorial appeared first on Codersee blog- Kotlin on the backend.

Hello 😀 In this article, I will show you how to implement a Reactive REST API with Micronaut and MongoDB (+ Project Reactor).

Nevertheless, if you are not interested in a reactive approach, and you would like to create a simple REST API, then check out my previous article related to Micronaut and Mongo.

Finally, just wanted to let you know that after this tutorial, you will know precisely:

• how to spin up a MongoDB instance with Docker,
• create a new Micronaut project with all dependencies using the Launch page,
• how to expose REST endpoints,
• and how to validate user input.

2. MongoDB Instance Setup

But before we create our Micronaut project, we need a MongoDB instance up and running on our local machine.

If you don’t have one, you can either install it with the official documentation or simply run the following Docker commands:

docker pull mongo

Then, start a new container named mongodb in a detached mode:

docker run -d -p 27017:27017 --name mongodb mongo

And finally, to validate use the docker ps command:

CONTAINER ID IMAGE COMMAND                CREATED       STATUS       PORTS                    NAMES
ce86244c3fe1 mongo "docker-entrypoint.s…" 5 seconds ago Up 4 seconds 0.0.0.0:27017->27017/tcp mongodb

3. Generate Reactive Micronaut with MongoDB Project

As the next step, let’s navigate to the Micronaut Launch. It is a web application, which allows us to generate new projects from scratch with ease. Of course, we have other possibilities, like Micronaut CLI, or cURL, but for simplicity, let’s go with the web approach:

As we can see, we will be using Micronaut 3.7.1 with Kotlin and JUnit.

Additionally, to set up reactive Micronaut with MongoDB, we will need the following features:

• reactor – adding reactive support using Project Reactor,
• mongo-reactive – bringing support for the MongoDB Reactive Streams Driver,
• data-mongodb-reactive – adding reactive data repositories for MongoDB.

With all of that being selected, let’s click the Generate Project button, download the ZIP file, and import it to our IDE.

4. application.yaml

As the next step after import, let’s make sure that our application.yaml is configured properly:

micronaut:
  application:
    name: mongodbasync
netty:
  default:
    allocator:
      max-order: 3
mongodb.uri: mongodb://${MONGO_HOST:localhost}:${MONGO_PORT:27017}/someDb

Please keep in mind to set the mongodb.uri to match your case.

With the above configuration, Micronaut will try to connect to the instance using localhost:27017 and use the someDb database. It’s worth mentioning here, that we don’t have to create the database manually- it will be created automatically if it does not exist.

5. Create Models and DTOs

Following, let’s add classes responsible for persisting and fetching data from MongoDB.

And as an introduction- in this project, we will expose functionality to manage articles and their authors.

5.1. Add Article Class

Firstly, let’s implement the Article:

@MappedEntity
data class Article(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val title: String,
  val category: ArticleCategory,
  val author: Author
)

As we can clearly see, we must annotate this class with:

• @MappedEntity– a generic annotation used to identify a persistent type. Without it, we would end up with an error: Internal Server Error: Can't find a codec for class com.codersee.model.Article, when adding a repository later.
• @Id – responsible for marking the identifier field. Without this one, on the other hand, the code won’t compile with the following message: Unable to implement Repository method: ArticleRepository.delete(Object entity). Delete all not supported for entities with no ID
• @GeneratedValue – annotating our property as a generated value.

Additionally, we make use of the @field to specify how exactly annotation should be generated in the Java bytecode.

5.2. Implement ArticleCategory

Nextly, let’s add a simple enum called ArticleCategory:

enum class ArticleCategory {
  JAVA, KOTLIN, JAVASCRIPT
}

It’s a simple enum, which will identify categories of our articles.

5.3. Create Author

Following, let’s implement the Author data class:

@Serializable
@Deserializable
data class Author(
  val firstName: String,
  val lastName: String,
  val email: String
)

This time, we have to mark the class with @Serializable and @Deserializable.

And although we don’t have to mark this class as an entity (it’s an inner JSON in the MongoDB document, not a separate one), we have to utilize these two annotations.

Without them, everything will fail with either:

Caused by: io.micronaut.core.beans.exceptions.IntrospectionException: No serializable introspection present for type Author author. Consider adding Serdeable. Serializable annotate to type Author author. Alternatively if you are not in control of the project’s source code, you can use @serdeimport(Author.class) to enable serialization of this type.

or

Caused by: io.micronaut.core.beans.exceptions.IntrospectionException: No deserializable introspection present for type: Author. Consider adding Serdeable.Deserializable annotate to type Author. Alternatively if you are not in control of the project’s source code, you can use @serdeimport(Author.class) to enable deserialization of this type.

5.4. Implement Requests

Finally, let’s implement two DTOs responsible for deserializing JSON payloads sent by the user: ArticleRequest and SearchRequest:

data class ArticleRequest(
  val title: String,
  val category: ArticleCategory,
  val author: Author
)

data class SearchRequest(
  val title: String
)

As we can see, these are just two, plain data classes with no annotations. And as mentioned above, their only responsibility will be to transfer the data deserialized from request bodies.

6. Make Use Of Data Repositories

With that being done, we can add the ArticleRepository to our reactive Micronaut with MongoDB project:

@MongoRepository
interface ArticleRepository : ReactorCrudRepository<Article, String> {

  @MongoFindQuery("{ title: { \$regex: :title, '\$options' : 'i'}}")
  fun findByTitleLikeCaseInsensitive(title: String): Flux<Article>

}

This time, we have to implement the desired repository and annotate the interface with @MongoRepository to make use of the data repositories in Micronaut.

Additionally, we’ve added a custom find query with @MongoFindQuery annotation. This function will be responsible for fetching articles by a given title.

Note: when we check the GenericRepository interface, we will see that we have plenty of possibilities to pick from:

In our case, we will go with the ReactorCrudRepository, which exposes basic CRUD operations with Fluxes and Monos.

7. Add Service Layer

Nextly, let’s implement the ArticleService:

@Singleton
class ArticleService(
  private val articleRepository: ArticleRepository
) {

  fun create(article: Article): Mono<Article> =
    articleRepository.save(article)

  fun findAll(): Flux<Article> =
    articleRepository.findAll()

  fun findById(id: String): Mono<Article> =
    articleRepository.findById(id)
      .switchIfEmpty(
        Mono.error(
          HttpStatusException(HttpStatus.NOT_FOUND, "Article with id: $id does not exists.")
        )
      )

  fun update(id: String, updated: Article): Mono<Article> =
    findById(id)
      .map { foundArticle -> updated.copy(id = foundArticle.id) }
      .flatMap(articleRepository::update)

  fun deleteById(id: String): Mono<Void> =
    findById(id)
      .flatMap(articleRepository::delete)
      .flatMap { deletedCount ->
        if (deletedCount > 0L)
          Mono.empty()
        else
          Mono.error(
            HttpStatusException(HttpStatus.NOT_FOUND, "Article with id: $id was not deleted.")
          )
      }

  fun findByTitleLike(name: String): Flux<Article> =
    articleRepository.findByTitleLikeCaseInsensitive(name)
}

As we can see, a lot is happening here, so let’s take a minute to understand this code snippet.

As the first thing, we mark the service with @Singleton, which means that the injector will instantiate this class only once. Then, we inject a previously created repository to make use of it.

7.1. create(), findAll() and findByTitleLike()

When it comes to these three functions there’s not too much to say about:

fun create(article: Article): Mono<Article> =
  articleRepository.save(article)

fun findAll(): Flux<Article> =
  articleRepository.findAll()

fun findByTitleLike(name: String): Flux<Article> =
  articleRepository.findByTitleLikeCaseInsensitive(name)

As we can clearly see, they are responsible for invoking appropriate functions from our repository and returning either Flux (multiple) or Mono (single) Article(s).

7.2. findById()

Nextly, let’s see the function responsible for fetching articles with their identifiers:

fun findById(id: String): Mono<Article> =
  articleRepository.findById(id)
    .switchIfEmpty(
      Mono.error(
        HttpStatusException(HttpStatus.NOT_FOUND, "Article with id: $id does not exists.")
      )
    )

Right here, we first invoke the findById(id) function from our repository. Then, it the article was found, we simply return the Mono<Article>.

Nevertheless, if the article does not exist in our MongoDB instance, the repository returns an empty Mono. And to handle this case, we use the switchIfEmpty() and translate it to the error Mono.

Finally, to return a meaningful status code and message to the user later, we use the HttpStatusException, which is a dedicated exception for that.

7.3. update()

Following, let’s take a look at the update() implementation:

fun update(id: String, updated: Article): Mono<Article> =
  findById(id)
    .map { foundArticle -> updated.copy(id = foundArticle.id) }
    .flatMap(articleRepository::update)

Right here, we first try to fetch the article by id. If it was found, then we simply copy its identifier to the instance with updated fields called updated.

As the last step, we invoke the update method from our repository using the function reference.

Note:  Function reference is a great syntatic sugar here and is an equivalent of: .flatMap{ articleRepository.update(it) } , or .flatMap{ updated -> articleRepository.update(updated) }.

7.4. deleteById()

Lastly, let’s check the delete functionality:

fun deleteById(id: String): Mono<Void> =
  findById(id)
    .flatMap(articleRepository::delete)
    .flatMap { deletedCount ->
      if (deletedCount > 0L)
        Mono.empty()
      else
        Mono.error(
          HttpStatusException(HttpStatus.NOT_FOUND, "Article with id: $id was not deleted.")
        )
    }

Similarly, we first try to find the article by id, and on success, we invoke the delete function from our repository.

As a result, we get a Long value indicating the number of affected (here- deleted) documents. So if this value is greater than 0, we simply return an empty Mono. Otherwise, we return an error Mono with HttpStatusException.

8. Controller For Reactive Micronaut with MongoDB

With all of that being done, let’s add the ArticleController class:

@Controller("/articles")
@ExecuteOn(TaskExecutors.IO)
class ArticleController(
  private val articleService: ArticleService
) {

  @Get
  fun findAll(): Flux<Article> =
    articleService.findAll()

  @Get("/{id}")
  fun findById(@PathVariable id: String): Mono<Article> =
    articleService.findById(id)

  @Post
  @Status(CREATED)
  fun create(@Body request: ArticleRequest): Mono<Article> =
    articleService.create(
      article = request.toArticle()
    )

  @Post("/search")
  fun search(@Body searchRequest: SearchRequest): Flux<Article> =
    articleService.findByTitleLike(
      name = searchRequest.title
    )

  @Put("/{id}")
  fun updateById(
    @PathVariable id: String,
    @Body request: ArticleRequest
  ): Mono<Article> =
    articleService.update(id, request.toArticle())

  @Delete("/{id}")
  @Status(NO_CONTENT)
  fun deleteById(@PathVariable id: String) =
    articleService.deleteById(id)

  private fun ArticleRequest.toArticle(): Article =
    Article(
      id = null,
      title = this.title,
      category = this.category,
      author = this.author
    )
}

As we can clearly see, we have to mark our controller class with the @Controller annotation and specify the base URI – /articles in our case.

Moreover, we make use of the @ExecuteOn(TaskExecutors.IO) to indicate which executor service a particular task should run on.

When it comes to particular functions, each one is responsible for handling different requests. Depending on which HTTP method should they respond to, we mark them with meaningful annotation: @Get, @Post, @Put, or @Delete. These annotations let us narrow down the URI route, like /search, or /{id}.

Additionally, we access path variables and request bodies with @PathVariable and @Body annotations (and DTOs implemented in paragraph 3), and set custom response codes with @Status. And of course, we have to remember that the status code can be changed with HttpStatusException in the service layer, as well.

9. Validation

At this point, our reactive Micronaut application can be run and we would be able to test the endpoints.

Nevertheless, before we do so, let’s add one more, crucial functionality: user input validation. In the following example, I will show you just a couple of possible validations, but please keep in mind that there are way more possibilities, which I encourage you to check out.

9.1. Edit Controller

As the first step, let’s make a few adjustments to the previously created controller:

// Make class open
open class ArticleController

// Add @Valid annotation and make functions open, as well
open fun create(@Valid @Body request: ArticleRequest): Mono<Article>

open fun search(@Valid @Body searchRequest: SearchRequest): Flux<Article>

open fun updateById(@PathVariable id: String, @Valid @Body request: ArticleRequest): Mono<Article>

As we can clearly see, to trigger the validation process for particular request bodies, we have to add the @Valid annotation.

Moreover, functions with validation must be marked as open. Without that, our Micronaut app won’t compile with the following error:

Method defines AOP advice but is declared final. Change the method to be non-final in order for AOP advice to be applied.

9.2. Change DTOs

Nextly, let’s make a couple of changes to the ArticleRequest, SearchRequest, and Author classes:

@Serializable
@Deserializable
data class Author(
  @field:NotBlank
  @field:Size(max = 50)
  val firstName: String,

  @field:NotBlank
  @field:Size(max = 50)
  val lastName: String,

  @field:Size(max = 50)
  @field:Email
  val email: String
)

@Introspected
data class ArticleRequest(
  @field:NotBlank val title: String,
  val category: ArticleCategory,
  @field:Valid val author: Author
)

@Introspected
data class SearchRequest(
  @field:NotBlank
  @field:Size(max = 50)
  val title: String
)

Firstly, we have to mark fields intended for validation with appropriate annotations, like @NotBlank, @Size, etc. These annotations are a part of the javax.validation.constraints package, which you might already know, for example from Spring Boot.

It’s worth mentioning two additional things we can see above: @Introspected and a @Valid annotation applied to the author.

With the first one, we state that the type should produce an io.micronaut.core.beans.BeanIntrospection at compilation time. Without it, Mirconaut won’t be able to process our annotations and all requests will fail at the runtime with the example message:

10. Testing

As the last step, we can finally run our reactive Micronaut application and check out if everything is working as expected with our MongoDB instance.

10.1. Create a New Article

Let’s start with creating a new Article:

curl --location --request POST 'http://localhost:8080/articles' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "title": "Title 1",
    "category": "JAVA",
      "author": {
        "firstName": "First Name 1",
        "lastName": "Last Name 1",
        "email": "one@gmail.com"
      }
  }'

# Result when successful: 
Status Code: 201 Created
Response Body: 
{
  "id": "634f9e825b223f0572585007",
  "title": "Title 1",
  "category": "JAVA",
  "author":
    {
      "firstName": "First Name 1",
      "lastName": "Last Name 1",
      "email": "one@gmail.com"
    }
}

# Response when validations failed: 
Status: 400 Bad Request
Response Body:
{
  "message": "Bad Request",
  "_embedded": {
  "errors": [
    {
      "message": "request.author.email: must be a well-formed email address"
    },
    {
      "message": "request.author.firstName: must not be blank"
    },
    {
      "message": "request.author.lastName: size must be between 0 and 50"
    },
    {
      "message": "request.title: must not be blank"
    }
  ]
},
  "_links": {
    "self": {
      "href": "/articles",
      "templated": false
    }
  }
}

As can be seen, everything is working correctly and validation works for both article and author payload.

10.2. List All Articles

Nextly, let’s list all articles:

curl --location --request GET 'http://localhost:8080/articles'

# Response:
Status Code: 200 OK 
Example response body: 
[
  {
    "id": "634f9fff5b223f0572585008",
    "title": "Title 1",
    "category": "JAVA",
    "author": {
      "firstName": "First Name 1",
      "lastName": "Last Name 1",
      "email": "one@gmail.com"
    }
  }
]

Everything is fine in this case.

10.3. GET Article By Id

Following, let’s get the details of the article by ID:

curl --location --request GET 'http://localhost:8080/articles/634fa0f05b223f057258500a'

# Response:
Status Code: 200 OK 
Example response body when found: 
{
  "id": "634fa0f05b223f057258500a",
  "title": "Another 2",
  "category": "JAVA",
  "author": {
    "firstName": "First Name 1",
    "lastName": "Last Name 1",
    "email": "one@gmail.com"
  }
}

# Response when article not found:
{
  "message": "Not Found",
  "_embedded": {
    "errors": [
      {
        "message": "Article with id: 634fa0f05b223f057258500b does not exists."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/articles/634fa0f05b223f057258500b",
      "templated": false
    }
  }
}

Similarly, works flawlessly for both cases.

10.4. Homework

The rest of the endpoints will be your homework and I highly encourage you to check them all.

Below, you can find the remaining cURLs, which can be used for testing:

# Update endpoint:
curl --location --request PUT 'http://localhost:8080/articles/634fa0f05b223f057258500a' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "title": "Changed Title",
    "category": "JAVASCRIPT",
    "author": {
      "firstName": "First Name 4",
      "lastName": "Last Name 4",
      "email": "two@gmail.com"
    }
  }'

# Search endpoint:
curl --location --request POST 'http://localhost:8080/articles/search' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "title": "1"
  }'

# Delete endpoint:
curl --location --request DELETE 'http://localhost:8080/articles/634cf9d458a6a33cdd19fdab'

10. Reactive Micronaut with MongoDB Summary

And that would be all for this article on how to expose REST API using Reactive Micronaut with MongoDB.

As always, you can find the whole source code in this GitHub repository.

If you find this material helpful (or not) or would like to ask me about anything, please leave a comment in the section below. I always highly appreciate your feedback and I am happy to chat with you 😀

Take care and have a great week!

The post Reactive REST API with Micronaut and MongoDB appeared first on Codersee blog- Kotlin on the backend.

Hi folks! In this step-by-step guide, I will show you how to create a REST API using Micronaut with MongoDB and Kotlin.

As you might have noticed, this article is a revisited version of another blog post, which I created a long time ago. And before we start I would like to commend for upgrade suggestions made via software development work from Software Prophets. Without Eric’s comments, involvement and feedback, this article would never have been written. Thanks! 😀

Finally, I just wanted to admit that after this blog post, you will know precisely:

• how to spin up a MongoDB instance with Docker,
• how to generate a new Micronaut project and add dependencies (like MongoDB) with ease,
• how to persist and read data with MongoClient and data repositories for MongoDB,
• how to expose REST endpoints.

2. New Micronaut with MongoDB and Kotlin Project

As the first step, let’s generate a new Micronaut project with MongoDB dependencies. We can do it in three ways:

• using Micronaut CLI,
• with cURL,
• or with the Micronaut Launch page.

And although the CLI is a preferred way to generate new projects, for simplicity, let’s have a look at how to do it with the Launch page:

As we can see, this website provides us with a clickable interface, where we can specify what exactly should our project consist of.

To be on the same page and make sure that everything works, as expected, let’s have a look at the options I’ve chosen:

• Application Type: Micronaut Application
• Micronaut Version: 3.7.1
• Java Version: 17
• Language: Kotlin
• Name: rest-mongodb (feel free to specify your own right here)
• Build Tool: Gradle Kotlin
• Base Package: com.codersee (similarly, you can pick whatever you want)
• Test Framework: JUnit
• Features: data-mongodb, mongo-sync (these two are important!)

With all of that being selected, let’s click the Generate Project button, download the Zip package, and open up the project with our favorite IDE (IntelliJ in my case).

3. Run MongoDB With Docker

Nextly, let’s set up a new MongoDB instance, which we will use to connect to it later. I’ll do it with Docker, but if you would like to install it on your local machine, you can find more information on this, official MongoDB page.
 

 
So, firstly, let’s pull the Mongo image:

docker pull mongo

As the next step, let’s start a new container named mongodb in a detached mode:

docker run -d -p 27017:27017 --name mongodb mongo

As we can see, additionally we have to expose the container’s port 27017 to some port of our local machine (and I used the exact same port to make everything simpler).

To validate, we can use the docker ps command:

CONTAINER ID IMAGE COMMAND                CREATED       STATUS       PORTS                    NAMES
ce86244c3fe1 mongo "docker-entrypoint.s…" 5 seconds ago Up 4 seconds 0.0.0.0:27017->27017/tcp mongodb

The above output indicates that our container is up and running and that the ports are mapped correctly.

4. Edit application.yaml File

After that is done, let’s get back to our project and edit the mongodb.uri property:

mongodb.uri: mongodb://localhost:27017/example

As we can see, apart from pointing to the desired host and location, we specify the database name we would like to use- example in our case.

5. Create Model Classes

As the next step, let’s implement two classes we will use in our Micronaut app to exchange data with MongoDB:

• AppUser– which will be responsible for transferring the data, like first and last name, email, and address of the application user,
• Address– which will be the inner class responsible for keeping user address information.

Let’s start with the second one, the Address class:

@Serializable
@Deserializable
data class Address(
  val street: String,
  val city: String,
  val code: Int
)

As we can see, in order to work with MongoDB, we have to mark our data class with @Serializable and @Deserializable annotations. No other annotation is necessary here as this class will not be mapped to any collection.

Additionally, the Micronaut creators deserve recognition here, because even if we forget to do so, we will see an exception with a meaningful message, like:

No serializable introspection present for type Address address. Consider adding Serdeable. Serializable annotate to type Address address. Alternatively if you are not in control of the project’s source code, you can use @SerdeImport(Address.class) to enable serialization of this type.

Or:

No deserializable introspection present for type: Address. Consider adding Serdeable.Deserializable annotate to type Address. Alternatively if you are not in control of the project’s source code, you can use @SerdeImport(Address.class) to enable deserialization of this type.

After that, let’s add the AppUser data class:

@MappedEntity
data class AppUser(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val firstName: String,
  val lastName: String,
  val email: String,
  val address: Address
)

This class, apart from the standard fields, has 4 features that are worth paying attention to:

• @MappedEntity – an annotation used to mark a class as being persisted.
• @field:Id – simply the @Id annotation applied to the backing field of Kotlin property. With this one, we designate that this field is the ID of an entity.
• @field:GeneratedValue– similarly, the @GeneratedValue annotation indicates that the property will have a generated value.
• val id: String? = null–  a nullable id property, with a null set by default. Thanks to that, the ID will be generated automatically.

6. Create DTOs

As the next step, let’s add DTOs to our Micronaut project.

Firstly, let’s implement the AppUserRequest:

data class AppUserRequest(
  val firstName: String,
  val lastName: String,
  val email: String,
  val street: String,
  val city: String,
  val code: Int
)

This class will be used to create and update users later.

Moreover, let’s add the SearchRequest:

data class SearchRequest(val name: String)

This one will be used later in search requests.

7. Micronaut With MongoDB and Data Repositories

As I mentioned in the introduction, in this Micronaut with MongoDB and Kotlin tutorial I would like to show you two different approaches on how to persist and fetch the data.

And in this paragraph, we’ll take a look at the synchronous data repositories for MongoDB.

7.1. Implement AppUserRepository

As the first step, let’s add the AppUserRepository interface:

@MongoRepository
interface AppUserRepository : CrudRepository<AppUser, String> 

As we can see, to make it a valid repository in terms of Micronaut, we have to mark our interface with the @MongoRepository annotation.

Additionally, we extend the generic CrudRepository providing the AppUser as the entity type and String as the ID type. As the name suggests, this repository let’s us perform CRUD operations, like save, update all, find, etc…

7.2. Make Use Of Finder Methods

Nextly, let’s make use of the finder methods feature. To put it simply, a finder method name will be translated to a valid query based on its name.

Let’s add the example definition to our interface:

fun findByFirstNameEquals(firstName: String): List<AppUser>

As the name suggests, when using this function all users with a first name equal to the passed argument will be returned. If you would like to learn a bit more about this functionality, then please check out this link to the documentation.

7.3. Custom Query With @MongoFindQuery

As the next step, let’s create a custom query with @MongoFindQuery annotation:

@MongoFindQuery("{ firstName: { \$regex: :name}}")
fun findByFirstNameLike(name: String): List<AppUser>

This time, the users will be returned if their first name contains a given String value. It’s worth mentioning that this annotation lets us specify additional sorting, filtering, or custom fields projections, as well.

Of course, find is not the only supported operation and we can make use of other annotations to specify update, delete, or aggregate queries:

• @MongoUpdateQuery
• @MongoDeleteQuery
• @MongoAggregateQuery

7.4. Create AppUserService

With all of the above being done, we have everything to implement the AppUserService:

@Singleton
class AppUserService(
  private val appUserRepository: AppUserRepository
) {

  fun create(userRequest: AppUserRequest): AppUser =
    appUserRepository.save(
      userRequest.toAppUserEntity()
    )

  fun findAll(): List<AppUser> =
    appUserRepository
      .findAll()
      .toList()

  fun findById(id: String): AppUser =
    appUserRepository.findById(id)
      .orElseThrow { HttpStatusException(HttpStatus.NOT_FOUND, "User with id: $id was not found.") }

  fun update(id: String, updateRequest: AppUserRequest): AppUser {
    val foundUser = findById(id)

    val updatedEntity =
      updateRequest
        .toAppUserEntity()
        .copy(id = foundUser.id)

    return appUserRepository.update(updatedEntity)
  }

  fun deleteById(id: String) {
    val foundUser = findById(id)

    appUserRepository.delete(foundUser)
  }

  fun findByNameLike(name: String): List<AppUser> =
    appUserRepository
      .findByFirstNameLike(name)

  private fun AppUserRequest.toAppUserEntity(): AppUser {
    val address = Address(
      street = this.street,
      city = this.city,
      code = this.code
    )

    return AppUser(
      id = null,
      firstName = this.firstName,
      lastName = this.lastName,
      email = this.email,
      address = address
    )
  }
}

As can be seen, we mark our service with a @Singleton annotation to indicate that it should be instantiated only once.

Let’s have a few words about each function:

• create(userRequest: AppUserRequest)– this one takes the AppUserRequest instance as an argument and invokes the toAppUserEntity() extension function returning a new AppUser instance. With this instance, we invoke the save() method returning the newly created object.
• findAll()– this function invokes the findAll() method from CrudRepository and converts returned Iterable to list.
• findById(id: String)– this one is a bit more interesting. Firstly, we invoke the findById() method returning an Optional of the AppUser. If it’s empty, we throw the HttpStatusException. In Micronaut, this class can be used to throw exceptions returning the desired status code and message. And that’s what we do here- as a result, the 400 Bad Request informing that the user with the given id was not found is returned.
• update(id: String, updateRequest: AppUserRequest)– as we can see, this one takes the desired id and an update request as the arguments. Firstly, we make use of already implemented findById() to fetch the desired user thus making sure he exists. Then, we simply convert our request to a new entity, but compared to the create(), have to set the id. Finally, we invoke the update() returning an updated user instance
• deleteById(id: String)– with this one we first make sure that the user exists and then, we invoke the delete() method of our repository.
• findByNameLike(name: String)– finally, this one is responsible for passing the name argument to our custom function: findByFirstNameLike(name).

8. Add Controller

As the last thing before we will be able to test our Micronaut with MongoDB and Kotlin application, let’s implement the AppUserController:

@Controller("/users")
@ExecuteOn(TaskExecutors.IO)
class AppUserController(
    private val appUserService: AppUserService
) {

    @Get
    fun findAllUsers(): List<AppUser> =
        appUserService.findAll()

    @Get("/{id}")
    fun findById(@PathVariable id: String): AppUser =
        appUserService.findById(id)

    @Post
    @Status(CREATED)
    fun createUser(@Body request: AppUserRequest): AppUser =
        appUserService.create(request)

    @Post("/search")
    fun searchUsers(@Body searchRequest: SearchRequest): List<AppUser> =
        appUserService.findByNameLike(
            name = searchRequest.name
        )

    @Put("/{id}")
    fun updateById(
        @PathVariable id: String,
        @Body request: AppUserRequest
    ): AppUser =
        appUserService.update(id, request)

    @Delete("/{id}")
    @Status(NO_CONTENT)
    fun deleteById(@PathVariable id: String) =
        appUserService.deleteById(id)
}

This time, everything starts with the @Controller annotation, where we put the base URI for this controller- “/users” in our case. As the name suggests, this annotation simply indicates that this class is a controller in our application.

Then, we specify the @ExecuteOn used to indicate which executor service use to run a particular task. In our case, we make use of the IO scheduler used to schedule I/O tasks (Thank you Captain Obvious 🙂 ) .

When it comes to the functions, we use the @Get, @Post, @Put, and @Delete annotations to specify what HTTP Methods they should handle and additional routes, like “/users/search”.  To bind a parameter from a path variable, we make use of the @PathVariable and @Body to do the same with a request body.

Finally, the @Status annotation is really useful to set the desired response code.

9. Testing

Let’s start by creating a new user with a POST request (and I highly recommend creating a few different users to better see if everything works, as expected):

curl --location --request POST 'localhost:8080/users' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "Piotr",
    "lastName": "Wolak",
    "email": "contact@codersee.com",
    "street": "Some Street",
    "city": "Some city",
    "code": 1
}'

# Response: 
{
    "id": "633c6fb788e9024f42951f18",
    "firstName": "Piotr",
    "lastName": "Wolak",
    "email": "contact@codersee.com",
    "address": {
        "street": "Some Street",
        "city": "Some city",
        "code": 1
    }
}

Secondly, let’s perform a GET request to see the list of all users:

curl --location --request GET 'localhost:8080/users/'

# Example Response: 
[
    {
        "id": "633c6fb788e9024f42951f18",
        "firstName": "Piotr",
        "lastName": "Wolak",
        "email": "contact@codersee.com",
        "address": {
            "street": "Some Street",
            "city": "Some city",
            "code": 1
        }
    }
]

Thirdly, let’s check if querying by ID works as expected in both cases:

curl --location --request GET 'localhost:8080/users/633c6fb788e9024f42951f18'

# User found:
{
    "id": "633c6fb788e9024f42951f18",
    "firstName": "Piotr",
    "lastName": "Wolak",
    "email": "contact@codersee.com",
    "address": {
        "street": "Some Street",
        "city": "Some city",
        "code": 1
    }
}

# User not found:
# Status: 404 Not Found
# Response body:
{
    "message": "Not Found",
    "_embedded": {
        "errors": [
            {
                "message": "User with id: 633c6fb788e9024f42951f19 was not found."
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/users/633c6fb788e9024f42951f19",
            "templated": false
        }
    }
}

Following, let’s perform an update:

curl --location --request PUT 'localhost:8080/users/633c6fb788e9024f42951f18' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "contact@codersee.com",
    "street": "Another Street",
    "city": "Another City",
    "code": 2
}'

# Response:
{
    "id": "633c6fb788e9024f42951f18",
    "firstName": "John",
    "lastName": "Doe",
    "email": "contact@codersee.com",
    "address": {
        "street": "Another Street",
        "city": "Another City",
        "code": 2
    }
}

# To verify, we can perform a GET request once again.

Before we check the DELETE endpoint, let’s make an example search query:

curl --location --request POST 'localhost:8080/users/search' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Joh"
}
'

# Result: 
[
    {
        "id": "633c6fb788e9024f42951f18",
        "firstName": "John",
        "lastName": "Doe",
        "email": "contact@codersee.com",
        "address": {
            "street": "Another Street",
            "city": "Another City",
            "code": 2
        }
    }
]

Finally, let’s delete the user:

curl --location --request DELETE 'localhost:8080/users/633c6fb788e9024f42951f18'

# Response:
# Status 204 No Content
# Response Body: empty

# If we repeat the request we should get: 
{
    "message": "Not Found",
    "_embedded": {
        "errors": [
            {
                "message": "User with id: 633c6fb788e9024f42951f18 was not found."
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/users/633c6fb788e9024f42951f18",
            "templated": false
        }
    }
}

As we can clearly see, everything is working, as expected.

10. Micronaut With MongoDB and MongoClient

Ok, so for now we’ve learned how to use Micronaut with MongoDB and Kotlin and data repositories for MongoDB.

Before we end this article, I would like to show you one more way to interact with a Mongo database- the MongoClient. According to the documentation, MongoClient is:

A client-side representation of a MongoDB cluster. Instances can represent either a standalone MongoDB instance, a replica set, or a sharded cluster. Instance of this class are responsible for maintaining an up-to-date state of the cluster, and possibly cache resources related to this, including background threads for monitoring, and connection pools.

Simply put- this class lets us operate on a MongoDB cluster. In our case, we will use it to perform operations on the example database and app_user collection.

11. Add AppUserWithMongoClientService

Although you probably don’t want to name classes in your project this way, I’d like to distinguish somehow between these two approaches 😀

With that being said, let’s implement the AppUserWithMongoClientService:

@Singleton
class AppUserWithMongoClientService(
    private val mongoClient: MongoClient
) {

    fun create(userRequest: AppUserRequest): BsonValue {
        val createResult = getCollection()
            .insertOne(userRequest.toAppUserEntity())

        return createResult.insertedId
            ?: throw HttpStatusException(HttpStatus.BAD_REQUEST, "User was not created.")
    }

    fun findAll(): List<AppUser> =
        getCollection()
            .find()
            .toList()

    fun findById(id: String): AppUser =
        getCollection()
            .find(
                Filters.eq("_id", ObjectId(id))
            )
            .toList()
            .firstOrNull()
            ?: throw HttpStatusException(HttpStatus.NOT_FOUND, "User with id: $id was not found.")

    fun update(id: String, updateRequest: AppUserRequest): AppUser {
        val updateResult = getCollection()
            .replaceOne(
                Filters.eq("_id", ObjectId(id)),
                updateRequest.toAppUserEntity()
            )

        if (updateResult.modifiedCount == 0L)
            throw HttpStatusException(HttpStatus.BAD_REQUEST, "User with id: $id was not updated.")

        return findById(id)
    }

    fun deleteById(id: String) {
        val deleteResult = getCollection()
            .deleteOne(
                Filters.eq("_id", ObjectId(id))
            )

        if (deleteResult.deletedCount == 0L)
            throw HttpStatusException(HttpStatus.BAD_REQUEST, "User with id: $id was not deleted.")
    }

    fun findByNameLike(name: String): List<AppUser> =
        getCollection()
            .find(
                Filters.regex("firstName", name)
            )
            .toList()


    private fun getCollection(): MongoCollection =
        mongoClient
            .getDatabase("example")
            .getCollection("app_user", AppUser::class.java)

    private fun AppUserRequest.toAppUserEntity(): AppUser {
        val address = Address(
            street = this.street,
            city = this.city,
            code = this.code
        )

        return AppUser(
            id = null,
            firstName = this.firstName,
            lastName = this.lastName,
            email = this.email,
            address = address
        )
    }

}

Just like previously, we can see that we annotated the class as a @Singleton and reuse the toAppUserEntity() extension function.

As you might have noticed, this time we added the getCollection() function responsible for getting a MongoCollection<AppUser> instances. This class lets us utilize methods, like find(), insertOne(), or deleteOne().

Moreover, in every function except the create() we make use of the Filters class, which is basically a factor for query filters.

12. Implement AppUserWithMongoClientService

And the last thing we will have to do in our Micronaut with MongoDB and Kotlin application is to add the AppUserWithMongoClientController:

@Controller("/users-client")
@ExecuteOn(TaskExecutors.IO)
class AppUserWithMongoClientController(
  private val appUserWithMongoClientService: AppUserWithMongoClientService
) {

  @Get
  fun findAllUsers(): List<AppUser> =
    appUserWithMongoClientService.findAll()

  @Get("/{id}")
  fun findById(@PathVariable id: String): AppUser =
    appUserWithMongoClientService.findById(id)

  @Post
  @Status(CREATED)
  fun createUser(@Body request: AppUserRequest): HttpResponse<Void> {
    val createdId = appUserWithMongoClientService.create(request)

    return HttpResponse.created(
      URI.create(
        createdId.asObjectId().value.toHexString()
      )
    )
  }

  @Post("/search")
  @Status(CREATED)
  fun searchUser(@Body searchRequest: SearchRequest): List<AppUser> =
    appUserWithMongoClientService.findByNameLike(
      name = searchRequest.name
    )

  @Put("/{id}")
  fun updateById(
    @PathVariable id: String,
    @Body request: AppUserRequest
  ): AppUser =
    appUserWithMongoClientService.update(id, request)

  @Delete("/{id}")
  @Status(NO_CONTENT)
  fun deleteById(@PathVariable id: String) =
    appUserWithMongoClientService.deleteById(id)

}

As we can see, this implementation is almost identical compared to the previous controller. Worth noting are two things:

• to avoid URI conflicts, this one responds to the /users-client,
• the createUser functionality works a bit differently- instead of returning the created entity, we make use of the 201 Created status code and pass the id of the created object as the location header. That wasn’t necessary, but I wanted to show you another approach, as well 😀

13. Test Additional Endpoints

Finally, we can test our new endpoints and make sure everything runs smoothly.

Nevertheless, I will not duplicate paragraph 10 right here, so this one will be your homework. There are two differences you have to remember about when testing this new controller, but if you’ve read the article thoroughly, I am pretty sure you will know exactly what I’m talking about.

14. Micronaut with MongoDB and Kotlin Revisited Summary

And that would be all for this article about Micronaut with MongoDB and Kotlin. If you’d like to see the whole source code, then please visit this GitHub repository.

Let me know if this article was useful for you in the comment section (or through the contact form– if that suits you best). Of course, if you feel this post is a total crap and do not recommend it- please leave a comment, as well- always happy to chat and open for criticism 🙂

Have a great day!

The post Micronaut with MongoDB and Kotlin Revisited [2022] appeared first on Codersee blog- Kotlin on the backend.

Hello dear readers. In this article, I would like to teach you how to create a Micronaut project with MongoDB and Kotlin.

Micronaut is a modern, JVM-based framework for building modular, easily testable microservice and serverless applications. If you have any prior experience with reflection-based frameworks, like Spring or Spring Boot, you probably noticed that the startup time and memory consumption are bound to the size of the codebase. With Micronaut, these problems have been solved using Java’s annotation processors, making it a really great choice for low memory-footprint environments, like microservices.

Moreover, the creators took a lot of inspiration from Spring and Grails, so if you’ve ever worked with any of them, you’ll see plenty of similarities.

In this guide, we will create a simple CRUD REST API, which will allow the user to operate on the data from MongoDB (for a similar project in Spring Boot, please see this article).

Note: I’ve released a newer, refreshed version of this article, which you can find right here.

2. Run MongoDB Server

Just like in previous articles, we need to make sure, that our MongoDB server is up and running. For simplicity, we will deploy it as a docker container. Nevertheless, if you would like to install a MongoDB on your local machine, please refer to this official manual.

2.1. Deploy MongoDB as a Container

Firstly, let’s pull the mongo image from the Docker Hub registry:

docker pull mongo

After that, let’s deploy it in a detached mode ( -d flag):

docker run -d -p 27017-27019:27017-27019 --name mongodb mongo

Besides deploying in a detached mode, the above command publishes the container’s ports to the host- in simple terms, we will be able to connect to the MongoDB using localhost.

Finally, let’s check if everything is OK with the following command:

docker ps

#command output
CONTAINER ID        IMAGE               COMMAND                  CREALTED             STATUS              PORTS                                  NAMES
26bd5c8dcc79        mongo               "docker-entrypoint.s…"   6 seconds ago       Up 5 seconds        0.0.0.0:27017-27019->27017-27019/tcp   mongodb

3. Set Up The Project

3.1. Generate The Project

As the first step, let’s generate the project. We can do that either by installing the Micronaut CLI or with the online launcher (similar to the Spring Initializr). In my case, I’ve generated it using the web launcher, setting the following values:

• Application Type: Micronaut Application
• Java Version: 11
• Base Package: com.codersee
• Name: example
• Micronaut Version: 2.2.1
• Language: Kotlin
• Build: Gradle Kotlin
• Test Framework: Junit
• Included Features: mongo-sync

Please notice, that we’ve included the mongo-sync feature, which will provide the support for the Mongo Synchronous Driver in our application.

3.2. Add The No-arg Compiler Plugin

Additionally, let’s add the no-arg compiler plugin inside the build.gradle.kts file:

plugins {
    id("org.jetbrains.kotlin.plugin.noarg") version "1.4.10"
}

The no-arg compiler plugin generates an additional zero-argument constructor for classes with a specific annotation. I’ll show you, how to create such annotation and why should we use it in the next chapters.

3.3. Configure application.yml

As the next step, let’s the MongoDB connection config inside the application.yml file:

micronaut:
  application:
    name: example
mongodb:
  uri: 'mongodb://localhost:27017/example'

This configuration instructs the MongoDB driver, that it should connect to the example database of the MongoDB instance running on port 27017.

4. Create @NoArg annotation

As the next step, let’s utilize the no-arg plugin and create the NoArg.kt file under the annotation package:

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class NoArg

Additionally, we have to add the following configuration inside the build.gradle.kts file:

noArg {
    annotation("com.codersee.annotation.NoArg")
}

Please keep in mind, that the parameter passed to the function, “com.codersee.annotation.NoArg” in my case, needs to match with the package inside your project.

5. Create Models

After all of the above being done, we can start defining models, which will be used to persist and fetch objects from the database. In our example, we will define two separate classes- a Company and an Employee:

@NoArg
data class Company(
    var id: ObjectId? = null,
    var name: String,
    var address: String
)

@NoArg
data class Employee(
    var id: ObjectId? = null,
    var firstName: String,
    var lastName: String,
    var email: String,
    var company: Company?,
)

As you might have noticed, both classes have been annotated with the @NoArg. Without it, we would have to make all of the fields nullable and that’s something I wanted to avoid.

5.1. What is ObjectId?

You might be wondering, what exactly the ObjectId is? Well, by default MongoDB uses ObjectIds as the default value of the _id field of each document. An ObjectId is a 12-byte BSON type having the following structure:

• The first 4 bytes represent the seconds since the Unix epoch
• The next 3 bytes are the machine identifier
• The next 2 bytes consists of process id
• The last 3 bytes are a random counter value

These 12 bytes altogether uniquely identify a document within the MongoDB collection and serve as a primary key for that document as well.

6. Add Custom Exception With Status Code

Nextly, let’s create a custom exception class named NotFoundException and ExceptionResponse, which will be used to serialize the response:

class NotFoundException(msg: String) : RuntimeException(msg)

class ExceptionResponse(
    val message: String?
)

NotFoundException is just a simple class extending the RuntimeException. Additionally, this class contains the msg field, which will be used to set and obtain the custom message.

With that being done, let’s create the NotFoundExceptionHandler class:

@Produces
@Singleton
class NotFoundExceptionHandler :
    ExceptionHandler<NotFoundException, HttpResponse<ExceptionResponse>> {

    override fun handle(
        request: HttpRequest<*>,
        exception: NotFoundException
    ): HttpResponse<ExceptionResponse> =
        HttpResponse.notFound(
            ExceptionResponse(
                message = exception.message
            )
        )

}

As you can see, we implement the ExceptionHandler interface and specify two things:

• The Throwable, we’d like to handle- NotFoundException in our case
• The result type- in our case, the  HttpResponse<ExceptionResponse>

Moreover, we provide the declaration for the handle function, in which we set the response body with the message from the exception and the 404 NOT FOUND response code.

6.1. What is @Singleton and @Produces?

Well, the @Signleton is used to register a Singleton in Micronaut’s application context (just like a @Component in Spring Boot). The @Produces annotation, on the other hand, is used to indicate, what MediaTypes will be produced by our component (by default, it’s set to the application/json).

7. Create Repositories

As the next step, let’s create repositories for our data. In our project, we’ll use the synchronous MongoClient to perform operations on the MongoDB.

7.1. Implement CompanyRepository

Let’s start by adding the CompanyRepository first:

@Singleton
class CompanyRepository(
    private val mongoClient: MongoClient
) {

    fun create(company: Company): InsertOneResult =
        getCollection()
            .insertOne(company)

    fun findAll(): List<Company> =
        getCollection()
            .find()
            .toList()

    fun findById(id: String): Company? =
        getCollection()
            .find(
                Filters.eq("_id", ObjectId(id))
            )
            .toList()
            .firstOrNull()

    fun update(id: String, update: Company): UpdateResult =
        getCollection()
            .replaceOne(
                Filters.eq("_id", ObjectId(id)),
                update
            )

    fun deleteById(id: String): DeleteResult =
        getCollection()
            .deleteOne(
                Filters.eq("_id", ObjectId(id))
            )

    private fun getCollection() =
        mongoClient
            .getDatabase("example")
            .getCollection("company", Company::class.java)
}

Let’s discuss, what exactly is happening in this class.

As the first step, we need to register it in the application context with @Signleton and inject the MongoClient instance through the constructor.

@Singleton
class CompanyRepository(
    private val mongoClient: MongoClient
) 

Nextly, we create the helper function, which will be responsible for getting the MongoCollection object of the company collection from the example database. Moreover, we pass the Company::class.java as the second parameter, so that all of the returned documents will be cast to this type.

private fun getCollection() =
    mongoClient
        .getDatabase("example")
        .getCollection("company", Company::class.java)

Following, let’s look at the functions responsible for getting the data from the database:

fun findAll(): List<Company> =
    getCollection()
        .find()
        .toList()

fun findById(id: String): Company? =
    getCollection()
        .find(
            Filters.eq("_id", ObjectId(id))
        )
        .toList()
        .firstOrNull()

As can be seen, in both cases the find() function has been used, returning the iterable, which we convert to the List. But, when looking for a specific company, we apply the additional filter looking for a document with the specified ID and either return the Company or null.

Lastly, let’s look at functions responsible for creating, updating, and deleting the data:

fun create(company: Company): InsertOneResult =
    getCollection()
        .insertOne(company)

fun update(id: String, update: Company): UpdateResult =
    getCollection()
        .replaceOne(
            Filters.eq("_id", ObjectId(id)),
            update
        )

fun deleteById(id: String): DeleteResult =
    getCollection()
        .deleteOne(
            Filters.eq("_id", ObjectId(id))
        )
}

As you can see, all of them return _Result instances. These classes contain a lot of useful information, like the count, or ID of affected documents (which we will use in the service layer).

7.2. Implement EmployeeRepository

Similarly, let’s implement the EmployeeRepository:

@Singleton
class EmployeeRepository(
    private val mongoClient: MongoClient
) {

    fun create(employee: Employee): InsertOneResult =
        getCollection()
            .insertOne(employee)

    fun findAll(): List =
        getCollection()
            .find()
            .toList()

    fun findAllByCompanyId(companyId: String): List<Employee> =
        getCollection()
            .find(
                Filters.eq("company._id", ObjectId(companyId))
            )
            .toList()


    fun findById(id: String): Employee? =
        getCollection()
            .find(
                Filters.eq("_id", ObjectId(id))
            )
            .toList()
            .firstOrNull()

    fun update(id: String, update: Employee): UpdateResult =
        getCollection()
            .replaceOne(
                Filters.eq("_id", ObjectId(id)),
                update
            )

    fun deleteById(id: String): DeleteResult =
        getCollection()
            .deleteOne(
                Filters.eq("_id", ObjectId(id))
            )

    private fun getCollection() =
        mongoClient
            .getDatabase("example")
            .getCollection("employee", Employee::class.java)
}

8. Create Services

8.1. Implement CompanyService

Before we will create the service, let’s add the CompanyRequest class, which will be used to store the data passed by the user:

class CompanyRequest(
    val name: String,
    val address: String
)

Nextly, let’s create the CompanyService class:

@Singleton
class CompanyService(
    private val companyRepository: CompanyRepository,
    private val employeeRepository: EmployeeRepository
) {

    fun createCompany(request: CompanyRequest): BsonValue? {
        val insertedCompany = companyRepository.create(
            Company(
                name = request.name,
                address = request.address
            )
        )
        return insertedCompany.insertedId
    }

    fun findAll():  List<Company> {
        return companyRepository.findAll()
    }

    fun findById(id: String): Company {
        return companyRepository.findById(id)
            ?: throw NotFoundException("Company with id $id was not found")
    }

    fun updateCompany(id: String, request: CompanyRequest): Company {
        val updateResult = companyRepository.update(
            id = id,
            update = Company(name = request.name, address = request.address)
        )

        if (updateResult.modifiedCount == 0L)
            throw throw RuntimeException("Company with id $id was not updated")

        val updatedCompany = findById(id)
        updateCompanyEmployees(updatedCompany)

        return updatedCompany
    }

    fun deleteById(id: String) {
        val deleteResult = companyRepository.deleteById(id)

        if (deleteResult.deletedCount == 0L)
            throw throw RuntimeException("Company with id $id was not deleted")
    }

    private fun updateCompanyEmployees(updatedCompany: Company) {
        employeeRepository
            .findAllByCompanyId(updatedCompany.id!!.toHexString())
            .map {
                employeeRepository.update(
                    it.id!!.toHexString(),
                    it.apply { it.company = updatedCompany }
                )
            }
    }
}

Basically, these are just simple functions responsible for creating, deleting, and retrieving the data through the CompanyRepository.

However, you might have noticed that each time, we would like to update the company, we need to update all employees connected with it. That’s because we keep the related company in denormalized form- inside the employee document. To visualize that, let’s check the example document from our database:

{
    "firstName": "Piotr",
    "lastName": "Wolak",
    "email": "contact@codersee.com",
    "company": {
        "_id": {
            "$oid": "5fcb90f830e3af4497f5de14"
        },
        "name": "Company Two",
        "company_address": "Address Two"
    },
    "_class": "com.codersee.mongocrud.model.Employee"
}

As you can see, the company document is stored as an inner document of each employee. This might seem pretty weird, especially when you have any previous experience working with SQL databases, but this is the optimal choice for most real-life scenarios when using MongoDB (if you would like to learn more about MongoDB relationships, please let me know and I will create another tutorial about it :).

8.2. Implement EmployeeService

In the same fashion, let’s create the EmployeeRequest responsible for data handling and the EmployeeService:

class EmployeeRequest(
    val firstName: String,
    val lastName: String,
    val email: String,
    val companyId: String?
)

@Singleton
class EmployeeService(
    private val employeeRepository: EmployeeRepository,
    private val companyService: CompanyService

) {

    fun createEmployee(request: EmployeeRequest): BsonValue? {
        val company = request.companyId?.let { companyService.findById(it) }

        val insertedEmployee = employeeRepository.create(
            Employee(
                firstName = request.firstName,
                lastName = request.lastName,
                email = request.email,
                company = company
            )
        )
        return insertedEmployee.insertedId
    }

    fun findAll(): List<Employee> =
        employeeRepository.findAll()

    fun findById(id: String): Employee =
        employeeRepository.findById(id)
            ?: throw NotFoundException("Employee with id $id not found")

    fun updateEmployee(id: String, request: EmployeeRequest): Employee {
        val foundCompany = request.companyId?.let { companyService.findById(it) }

        val updateResult = employeeRepository.update(
            id = id,
            update = Employee(
                firstName = request.firstName,
                lastName = request.lastName,
                email = request.email,
                company = foundCompany
            )
        )

        if (updateResult.modifiedCount == 0L)
            throw throw RuntimeException("Employee with id $id was not updated")

        return findById(id)
    }

    fun deleteById(id: String) {
        val deleteResult = employeeRepository.deleteById(id)

        if (deleteResult.deletedCount == 0L)
            throw throw RuntimeException("Company with id $id was not deleted")
    }
}

9. Implement REST Controllers

As the last step, we will implement the controller layer responsible for request handling. But before that, let’s prepare two classes: CompanyResponse and EmployeeResponse responsible for returning the data to the user.

Important note: although the creation of separate classes for transferring the incoming and outgoing data adds some redundancy to the code, I personally believe it is a good way to separate these concepts and make the code cleaner.

class CompanyResponse(
    val id: String,
    val name: String,
    val address: String
) {
    companion object {
        fun fromEntity(company: Company): CompanyResponse =
            CompanyResponse(
                id = company.id!!,
                name = company.name,
                address = company.address
            )
    }
}

class EmployeeResponse(
    val id: String,
    val firstName: String,
    val lastName: String,
    val email: String,
    val company: CompanyResponse?
) {
    companion object {
        fun fromEntity(employee: Employee): EmployeeResponse =
            EmployeeResponse(
                id = employee.id!!.toHexString(),
                firstName = employee.firstName,
                lastName = employee.lastName,
                email = employee.email,
                company = employee.company?.let { CompanyResponse.fromEntity(it) }
            )
    }
}

As you can see, both classes contain fromEntity functions inside companion objects. As the name suggests, they will be used to convert entity objects to response instances.

9.1. Create CompanyController

Let’s add the CompanyController class to our project first:

@Controller("/api/company")
class CompanyController(
    private val companyService: CompanyService
) {

    @Post
    fun create(@Body request: CompanyRequest): HttpResponse<Void> {
        val createdId = companyService.createCompany(request)

        return HttpResponse.created(
            URI.create(
                createdId!!.asObjectId().value.toHexString()
            )
        )
    }

    @Get
    fun findAll(): HttpResponse<List<CompanyResponse>> {
        val companies = companyService
            .findAll()
            .map { CompanyResponse.fromEntity(it) }

        return HttpResponse.ok(companies)
    }

    @Get("/{id}")
    fun findById(@PathVariable id: String): HttpResponse<CompanyResponse> {
        val company = companyService.findById(id)

        return HttpResponse.ok(
            CompanyResponse.fromEntity(company)
        )
    }

    @Put("/{id}")
    fun update(
        @PathVariable id: String,
        @Body request: CompanyRequest
    ): HttpResponse<CompanyResponse> {
        val updatedCompany = companyService.updateCompany(id, request)

        return HttpResponse.ok(
            CompanyResponse.fromEntity(updatedCompany)
        )
    }

    @Delete("/{id}")
    fun deleteById(@PathVariable id: String): HttpResponse<Void> {
        companyService.deleteById(id)

        return HttpResponse.noContent()
    }
}

As you can see,  in order to make the class a controller inside the Micronaut context, we need to annotate it with @Controller. Additionally, we can pass the base URI to it, as we’ve done in the above code snippet.

Basically, the CompanyController utilizes already prepared functions from the CompanyService. Each function needs to be marked with appropriate annotation (like @Get, @Put, etc.) in order to serve as an HTTP request handler. By default, it will use the base URI set for the class (/api/company in our case).

As the last thing, please notice the @PathVariable- used to bind the parameter of the function exclusively from the path variable- and the @Body– indicating that the method argument is bound from the HTTP body.

9.2. Create EmployeeController

Similarly, let’s implement the EmployeeController:

@Controller("/api/employee")
class EmployeeController(
    private val employeeService: EmployeeService
) {

    @Post
    fun create(@Body request: EmployeeRequest): HttpResponse {
        val createdId = employeeService.createEmployee(request)

        return HttpResponse.created(
            URI.create(
                createdId!!.asObjectId().value.toHexString()
            )
        )
    }

    @Get
    fun findAll(): HttpResponse<List> {
        val employees = employeeService
            .findAll()
            .map { EmployeeResponse.fromEntity(it) }

        return HttpResponse.ok(employees)
    }

    @Get("/{id}")
    fun findById(@PathVariable id: String): HttpResponse {
        val employee = employeeService.findById(id)

        return HttpResponse.ok(
            EmployeeResponse.fromEntity(employee)
        )
    }

    @Put("/{id}")
    fun update(
        @PathVariable id: String,
        @Body request: EmployeeRequest
    ): HttpResponse {
        val updatedEmployee = employeeService.updateEmployee(id, request)

        return HttpResponse.ok(
            EmployeeResponse.fromEntity(updatedEmployee)
        )
    }

    @Delete("/{id}")
    fun deleteById(@PathVariable id: String): HttpResponse {
        employeeService.deleteById(id)

        return HttpResponse.noContent()
    }
}

10. Test with CURL

Finally, we can run our application- for instance, with the ./gradlew run command- and test the endpoints using cURL. If you would like to explore the database, I highly recommend the MongoDB Compass, which is the dedicated GUI for MongoDB.

Let’s start by adding two companies:

# 1st company
curl --location --request POST 'localhost:8080/api/company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Company 1",
    "address": "Address 1"
}'

# 2nd company
curl --location --request POST 'localhost:8080/api/company' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Company 2",
    "address": "Address 2"
}'

To validate, let’s list all companies:

curl --location --request GET 'localhost:8080/api/company'

# Example output
[
  {
    "id": "5fcba07a30e3af4497f5de16",
    "name": "Company 1",
    "address": "Address 1"
  },
  {
    "id": "5fcba07c30e3af4497f5de17",
    "name": "Company 2",
    "address": "Address 2"
  }
]

If we would like to find a specific company, then let’s use the following command:

curl --location --request GET 'localhost:8080/api/company/5fcba07c30e3af4497f5de17'

# Expected output
{
  "id": "5fcba07c30e3af4497f5de17",
  "name": "Company 2",
  "address": "Address 2"
}

To update the company, let’s use the PUT request:

curl --location --request PUT 'localhost:8080/api/company/5fcba07c30e3af4497f5de17' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Company 2 Updated",
    "address": "Address 2 Updated"
}'

If everything went well, we should see that our company data has been updated- you can always check it with another endpoint as well.

To delete the company, let’s use the DELETE handling endpoint:

curl --location --request DELETE 'localhost:8080/api/company/5fcba07c30e3af4497f5de17'

This time, we should receive an empty response body with 204 No Content status and a company should be deleted as well.

Similarly, we can test the rest of the endpoints responsible for employees management- let it be homework for you- I’ve always believed there is no other way to learn anything, than trying on our own 🙂

11. Summary

And that’s all for this article. We’ve gone step by step through the process of creating the Micronaut project with MongoDB and Kotlin

I hope, you really enjoyed it and that after reading it, you’ll get more interested in the Micronaut project. If you would like to ask about anything or add your own suggestions, please do it in the comment section below, or by using the contact form.

As usual, you can find the working project in this GitHub repository.

The post Micronaut with MongoDB and Kotlin appeared first on Codersee blog- Kotlin on the backend.