Hello friend! 🙂 Welcome to my next practical tutorial, in which I will show you how to expose web endpoints using Spring Boot 3 and Kotlin router DSL (aka- functional style).

Basically, the Kotlin router DSL comes in 3 variants:

• WebMvc.fn DSL using router { } – which we can use when working with a “standard” MVC Spring Project,
• WebFlux.fn Reactive DSL with router { } – used when working with a reactive-stack framework- Spring Webflux,
• WebFlux.fn Coroutines DSL with coRouter { } – as the name suggests- the one we will use when working with coroutines.

And although in this article, we will make use of the coroutine-based REST API implemented in “Reactive REST API With Spring, Kotlin, and Coroutines“, the knowledge you’re gonna gain today is universal and will work regardless of the implementation.

Video Tutorial

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

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

2. Project Configuration

As I mentioned in the introduction, we will reuse the already implemented API and rewrite the @RestController approach using the Spring Boot Kotlin DSL router.

[elementor-template id=”9007393″]

So, as the first step, let’s clone this GitHub repository.

When we navigate to the controller package, we will see that the project contains 3 controllers:

• UserController
• SearchController
• CompanyController

And for the purpose of this tutorial, we will focus on the API responsible for users management:

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

  @PostMapping
  suspend fun createUser(@RequestBody userRequest: UserRequest): UserResponse =
    userService.saveUser(
        user = userRequest.toModel()
    )
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  @GetMapping
  suspend fun findUsers(
    @RequestParam("name", required = false) name: String?
  ): Flow {
    val users = name?.let { userService.findAllUsersByNameLike(name) }
      ?: userService.findAllUsers()

    return users.map(User::toResponse)
  }

  @GetMapping("/{id}")
  suspend fun findUserById(
    @PathVariable id: Long
  ): UserResponse =
    userService.findUserById(id)
      ?.let(User::toResponse)
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  @DeleteMapping("/{id}")
  suspend fun deleteUserById(
    @PathVariable id: Long
  ) {
    userService.deleteUserById(id)
  }

  @PutMapping("/{id}")
  suspend fun updateUser(
    @PathVariable id: Long,
    @RequestBody userRequest: UserRequest
  ): UserResponse =
    userService.updateUser(
      id = id,
      requestedUser = userRequest.toModel()
    )
      .toResponse()
}

private fun UserRequest.toModel(): User =
  User(
    email = this.email,
    name = this.name,
    age = this.age,
    companyId = this.companyId
  )

fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id!!,
    email = this.email,
    name = this.name,
    age = this.age
  )

3. Convert UserController To Handler

Before we will start working with Spring Boot Kotlin DSL, let’s make a few adjustments.

Firstly, let’s add a new package called handler.

Then, let’s remove all annotations inside the class and mark the UserHandler with @Component:

@Component
class UserHandler(
    private val userService: UserService
) {

  suspend fun createUser(userRequest: UserRequest): UserResponse =
    userService.saveUser(
      user = userRequest.toModel()
    )
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  suspend fun findUsers(
    name: String?
  ): Flow {
    val users = name?.let { userService.findAllUsersByNameLike(name) }
      ?: userService.findAllUsers()

    return users.map(User::toResponse)
  }

  suspend fun findUserById(
    id: Long
  ): UserResponse =
    userService.findUserById(id)
      ?.let(User::toResponse)
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  suspend fun deleteUserById(
    id: Long
  ) {
    userService.deleteUserById(id)
  }

  suspend fun updateUser(
    id: Long,
    userRequest: UserRequest
  ): UserResponse =
    userService.updateUser(
      id = id,
      requestedUser = userRequest.toModel()
    )
      .toResponse()
}

4. Implement Coroutines router with Kotlin DSL

With all of that being done, let’s create a new class Config inside the config package:

@Configuration
class Config {

  @Bean
  fun router(
    userHandler: UserHandler
  ) = coRouter {
    accept(MediaType.APPLICATION_JSON).nest {

      "/api/users".nest {
        POST("", userHandler::createUser)
        GET("", userHandler::findUsers)
        GET("/{id}", userHandler::findUserById)
        DELETE("/{id}", userHandler::deleteUserById)
        PUT("/{id}", userHandler::updateUser)
      }

    }
  }

}

As I mentioned in the beginning when working with coroutines, we will create a RouterFunction using coRouter{ }. Nevertheless, when working with MVC or Spring WebFlux, then the choice would be the router {}.

As we can see, the nest {} function allows us to structure routing in a neat and readable manner.

Let’s take a look at the following example:

"/api/v1".nest {
  "/whatever".nest {
    "/sub-whatever".nest {
      // whatever
    }
  }
}

"/api/v2".nest {
  // another handlers
}

This way, we can manage versioning in one place.

Nevertheless, let’s get back to our user handlers:

POST("", userHandler::createUser)
GET("", userHandler::findUsers)
GET("/{id}", userHandler::findUserById)
DELETE("/{id}", userHandler::deleteUserById)
PUT("/{id}", userHandler::updateUser)

At this point, our application won’t compile, because of one, important thing- handler functions must take only one parameter of the ServerRequest type.

So in order to fix the app, we will have to update our Spring controller for functional routing.

5. Update POST Endpoint

So as the first step, let’s make the necessary adjustments to the createUser:

suspend fun createUser(request: ServerRequest): ServerResponse {
  val userRequest = request.awaitBody(UserRequest::class)

  val savedUserResponse = userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  return ServerResponse.ok()
    .bodyValueAndAwait(savedUserResponse)
}

// Before:


@PostMapping
suspend fun createUser(@RequestBody userRequest: UserRequest): UserResponse =
  userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

As we can see, instead of binding the JSON payload to the UserRequest instance with an annotation, we have to do it manually with .awaitBody().

Whatsoever, the return type changes to ServerResponse, which we have to create manually.

And although the final choice is up to you, instead of throwing the ResponseStatusException, we can compose the HTTP error response on our own:

suspend fun createUser(request: ServerRequest): ServerResponse {
  val userRequest = request.awaitBody(UserRequest::class)

  return userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?.let { response ->
      ServerResponse.ok()
        .bodyValueAndAwait(response)
    }
    ?: ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
      .buildAndAwait()
}

6. Migrate GET All Users

Nextly, let’s migrate the findUsers() function and learn how to read query parameters:

suspend fun findUsers(
  request: ServerRequest
): ServerResponse {
  val users = request.queryParamOrNull("name")
    ?.let { name -> userService.findAllUsersByNameLike(name) }
    ?: userService.findAllUsers()

  val usersResponse = users.map(User::toResponse)

  return ServerResponse.ok()
    .bodyAndAwait(usersResponse)
}

// Before:

@GetMapping
suspend fun findUsers(
  @RequestParam("name", required = false) name: String?
): Flow {
  val users = name?.let { userService.findAllUsersByNameLike(name) }
    ?: userService.findAllUsers()

  return users.map(User::toResponse)
} 

This time, in order to read a particular query parameter, we can use the queryParamOrNull(String). However, the ServerRequest interface comes with two, additional functions, which we could use here:

• queryParam(String), which returns the Optional,
• and queryParams() returning an instance of MultiValueMap<String, String> with all parameters.

And just, like previously we compose a ServerResponse instance, but this time using the bodyAndAwait(), which takes a Flow as an argument.

7. GET User By Id

As the next example in our Spring Boot Kotlin DSL project, let’s rewrite the findUserById() and see how we can read a path variable:

suspend fun findUserById(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()

  val userResponse = userService.findUserById(id)
    ?.let(User::toResponse)
    ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  return ServerResponse.ok()
    .bodyValueAndAwait(userResponse)
}

// Before:

@GetMapping("/{id}")
suspend fun findUserById(
  @PathVariable id: Long
): UserResponse =
  userService.findUserById(id)
    ?.let(User::toResponse)
    ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

As we can see, in order to read the path variable, we have to use the pathVariable(String) (or alternatively, pathVariables()). Unfortunately, this function cannot be parametrized and we have to take care of Long conversions manually.

8. DELETE Endpoint

Following, let’s update the deleteUserById():

suspend fun deleteUserById(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()

  userService.deleteUserById(id)

  return ServerResponse.noContent()
    .buildAndAwait()
}

// Before: 

@DeleteMapping("/{id}")
suspend fun deleteUserById(
  @PathVariable id: Long
) {
  userService.deleteUserById(id)
}

And this time, instead of returning anything in the response payload, we make use of the noContent() along with buildAndAwait() to return a bodiless entity.

9. User Update With PUT

Lastly, let’s make the necessary adjustments to the updateUser():

suspend fun updateUser(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()
  val userRequest = request.awaitBody(UserRequest::class)

  val userResponse = userService.updateUser(
    id = id,
    requestedUser = userRequest.toModel()
  ).toResponse()

  return ServerResponse.ok()
    .bodyValueAndAwait(userResponse)
}

// Before:

@PutMapping("/{id}")
suspend fun updateUser(
  @PathVariable id: Long,
  @RequestBody userRequest: UserRequest
): UserResponse =
  userService.updateUser(
    id = id,
    requestedUser = userRequest.toModel()
  )
    .toResponse()

As we can see, nothing new shows up in this example.

10. Testing And Homework

With all of that being done, we can finally run our application and verify whether handlers are working, as expected.

Your homework will be to:

1. Test whether the routing works fine after we converter our Spring controller to the functional style.
2. Refactor the CompanyController and SearchController classes in a similar manner.

As a bonus, right here you can find a Postman collection, which you can use for testing.

Note: If you would like to see the solution, then check out the router-dsl branch in my GitHub repo.

11. Spring Boot 3 With Kotlin DSL Summary

And that’s all for this tutorial, in which we have learned how to expose web endpoints using Spring Boot 3 and Kotlin router DSL (aka- functional style).

Hope you enjoyed this content, and if so, then please reach out in the comments section.

Have a great week!

The post Spring Boot 3 Kotlin Router DSL appeared first on Codersee blog- Kotlin on the backend.

Welcome to my next article, in which I will show you everything you need to know when working with Spring WebClient and Kotlin coroutines.

To be on the same page- this article will be a coroutine-focused extension of my other blog post about Spring 5 WebClient with Spring Boot. So, instead of duplicating the content, which works exactly the same regardless of whether we pick the Reactor or coroutines implementation, I will focus on response handling. Nevertheless, if you are interested in other features, like request bodies, headers, and filter implementation, then I recommend checking out that article, as well.

With that being said, let’s get to work 🙂

Video Tutorial

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

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

2. API Specification

Before I show you how to implement WebClient with Kotlin coroutines, let me quickly describe the API we are about to query.

Basically, we will be using 3 endpoints in order to:

• fetch a list of all users,
• get user by its identifier,
• and delete a particular user by id.

And to better visualize, let’s take a look at the API “contract”:

GET http://localhost:8090/users 

# Example response:
[
  {
    "id": 1,
    "first_name": "Robert",
    "last_name": "Smith"
  },
  {
    "id": 2,
    "first_name": "Mary",
    "last_name": "Jones"
  }
...
]

GET http://localhost:8090/users/1

# Example successful response body:
{
  "id": 1,
  "first_name": "Robert",
  "last_name": "Smith"
}

# If the user is not found, then the API returns 404 NOT FOUND

DELETE http://localhost:8090/users/1

# Responds 204 No Content with empty body

[elementor-template id=”9007393″]

3. Configure Spring WebClient

And although the Spring WebClient configuration does not differ when working with coroutines, let’s take a look at the config class:

@Configuration
class Config {

  @Bean
  fun webClient(builder: WebClient.Builder): WebClient =
      builder
        .baseUrl("http://localhost:8090")
        .build()
}

As we can see, with this config we define a new WebClient bean and instruct that a base URL for our requests is http://localhost:8090.

4. Implement UserResponse

Nextly, let’s add the UserResponse class to our codebase:

data class UserResponse(
  val id: Long,
  @JsonProperty("first_name") val firstName: String,
  @JsonProperty("last_name") val lastName: String
)

And this class will be responsible for serializing responses from the external API.

5. Spring WebClient With Kotlin Coroutines

As the next step, we can finally implement the UserApiService and start querying.

Of course, let’s inject the WebClient before heading to the next steps:

@Service
class UserApiService(
  private val webClient: WebClient
) {

}

5.1 Obtaining Response Body With awaitBody()

Firstly, let’s learn how to fetch a list of users:

suspend fun findAllUsers(): List<UserResponse> =
  webClient.get()
    .uri("/users")
    .retrieve()
    .awaitBody<List<UserResponse>>()

Well, we have to remember that the awaitBody() is a suspend function- and that’s the reason why our function is defined as a suspend, as well. Moreover, we have to define the type of response we are expecting (List<UserResponse> in our case). Of course, it’s optional if we already defined a return type explicitly for our function.

5.2 awaitBodyOrNull()

Additionally, we can make use of another variant, awaitBodyOrNull():

suspend fun findUserById(id: Long): UserResponse? =
  webClient.get()
    .uri("/users/$id")
    .retrieve()
    .awaitBodyOrNull<UserResponse>()

This time, if the Mono completes without a value, a null is returned.

Nevertheless, please keep in mind that by default when using retrieve() 4xx and 5xx responses result in a WebClientResponseException. Later, I will show you how to customize this behavior using onStatus().

5.3 Return User List As A Flow

As the next step, let’s learn how to transform our publisher into Flow:

fun findAllUsersFlow(): Flow<UserResponse> =
  webClient.get()
    .uri("/users")
    .retrieve()
    .bodyToFlow<UserResponse>()

This time, instead of converting users’ responses into a List, we invoke the .bodyToFlow<UserResponse>(), which underneath transforms a Flux<UserResponse> into the Flow.

5.4 WebClient retrieve vs exchange

Well, although I promised not to cover things twice, I believe it’s important to say a couple of words here.

The main difference between retrieve() and exchange() methods is that the exchange() returns additional HTTP information, like headers and status. Nevertheless, when using it, it is our responsibility to handle all response cases to avoid memory leaks! And because of that, the exchange() was deprecated in Spring 5.3 and we should rather use exchangeToMono(Function) and exchangeToFlux(Function)(of course, if the retrieve() is not sufficient for our needs).

When working with Spring WebClient and Kotlin coroutines, we can make use of the awaitExchange and exchangeToFlow functions.

5.5 awaitExchange()

With that being said, let’s implement another function using awaitExchange:

suspend fun findAllUsersUsingExchange(): List<UserResponse> =
  webClient.get()
    .uri("/users")
    .awaitExchange { clientResponse ->
      val headers = clientResponse.headers().asHttpHeaders()
      logger.info("Received response from users API. Headers: $headers")
      clientResponse.awaitBody<List<UserResponse>>()
    }

As we can see, this function can be a good choice if we would like to access additional response information (like headers in our case) and perform additional logic based on them.

5.6 exchangeToFlow()

On the other hand, if we would like to return the Flow, then we must choose exchangeToFlow variant:

fun findAllUsersFlowUsingExchange(): Flow<UserResponse> =
  webClient.get()
    .uri("/users")
    .exchangeToFlow { clientResponse ->
      val headers = clientResponse.headers().asHttpHeaders()
      logger.info("Received response from users API. Headers: $headers")
      clientResponse.bodyToFlow<UserResponse>()
    }

5.7 Work With Bodiless

Sometimes, the REST API endpoints do not return any response body, which is usually indicated by the 204 No Content status code.

In such a case we can either choose awaitBody and pass the Unit type, or awaitBodilessEntity:

suspend fun deleteUserById(id: Long): Unit =
  webClient.delete()
    .uri("/users/$id")
    .retrieve()
    .awaitBody<Unit>()

suspend fun deleteUserById(id: Long): ResponseEntity<Void> =
  webClient.delete()
    .uri("/users/$id")
    .retrieve()
    .awaitBodilessEntity()

As we can see, depending on our needs we can either simply return the Unit or the ResponseEntity instance.

5.8 Handling Errors

And although the last example does not differ when working with WebClient and Kotlin coroutines, I feel obliged to show how we can handle API error status codes.

As I mentioned previously, by default all 4xx and 5xx response status codes cause WebClientResponseException to be thrown. And if we would like to alter this behavior, Spring WebFlux comes with a useful onStatus method for that:

suspend fun findUserByIdNotFoundHandling(id: Long): UserResponse =
  webClient.get()
    .uri("/users/$id")
    .retrieve()
    .onStatus({ responseStatus ->
      responseStatus == HttpStatus.NOT_FOUND
    }) { throw ResponseStatusException(HttpStatus.NOT_FOUND) }
    .awaitBody<UserResponse>()

The onStatus takes two parameters: the predicate and a function. In our example, each 404 Not Found response from the external API will be translated to ResponseStatusException with the same HttpStatus.

6. Spring WebClient With Kotlin Coroutines Summary

And that’s all for this article. Together, we’ve learned how easily we can implement a Spring WebClient with Kotlin coroutines using built-in features.

As always, you can find the example source code in this GitHub repository and I will be thankful if you would like to share some feedback with me right here, in the comments section.

The post Spring WebClient With Kotlin Coroutines appeared first on Codersee blog- Kotlin on the backend.

Hello friend! In this, practical step-by-step guide, I will teach you how to create a reactive REST API using Spring, Kotlin, coroutines, and Kotlin Flows entirely from scratch.

And although Spring internally uses Reactor implementation, coroutines provide a more straightforward and natural way of writing asynchronous, non-blocking code. Thanks to this, we can enjoy the benefits of a non-blocking code without compromising the readability of the code (which might become an issue when using Project Reactor in more mature and complex projects).

At the end of this tutorial, you will know precisely how to:

• set up a Spring Boot 3 project to work with Kotlin coroutines,
• run a PostgreSQL instance using Docker,
• create an example database and a schema,
• query and persist data using R2DBC and CoroutineCrudRepository,
• expose reactive REST API with coroutines and Kotlin Flows.

So, without any further ado, let’s get to work 🙂

Video Tutorial

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

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

2. PostgreSQL DB

As the first step, let’s learn how to set up a fresh PostgreSQL instance using Docker and populate it with the necessary data. Of course, feel free to skip step 2.1 if you already have some development database installed.

2.1 Start a Postgres Instance

In order to start a fresh instance, let’s navigate to the terminal and specify the following command:

docker run --name some-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

After that, let’s wait a while until the database is up and running.

We can additionally verify if that’s the case using docker ps:

CONTAINER ID IMAGE    COMMAND                CREATED     STATUS           PORTS                  NAMES
1863e6ec964a postgres "docker-entrypoint.s…" 6 hours ago Up About an hour 0.0.0.0:5432->5432/tcp some-postgres

This one, simple command results in a couple of interesting things happening underneath:

• firstly, it creates a new container named some-postgres and exposes its port 5432 to 5432 of the host machine (localhost in most cases),
• secondly, it creates a default Postgres user called postgres and sets its password using the POSTGRES_PASSWORD environment value (of course, we can create another user using the POSTGRES_USER environment variable),
• and lastly, it starts in a detached mode thanks to the -d flag.

[elementor-template id=”9007393″]

2.2 Create And Populate The Database

As the next step, let’s connect to the database, and create a schema with two tables:

create schema if not exists application;

create table if not exists application.company(
  id serial not null primary key,
  name varchar(255) not null,
  address varchar(255) not null
);

create table if not exists application.app_user(
  id serial not null primary key,
  email varchar(255) not null unique,
  name varchar(255) not null,
  age int not null, 
  company_id bigint not null references application.company(id) on delete cascade
);

As we can see, the purpose of our application will be users and companies management. Each user will have to be assigned to some company. Moreover, if a company is deleted, then the related user rows will be removed, as well.

Additionally, we can populate tables with the following script:

insert into application.company(name, address) values
  ('Company 1', 'Address 1'),
  ('Company 2', 'Address 2'),
  ('Company 3', 'Address 3');

insert into application.app_user(email, name, age, company_id) values
  ('email-1@codersee.com', 'John', 23, 1),
  ('email-2@codersee.com', 'Adam', 33, 1),
  ('email-3@codersee.com', 'Maria', 40, 2),
  ('email-4@codersee.com', 'James', 39, 3),
  ('email-5@codersee.com', 'Robert', 41, 3),
  ('email-6@codersee.com', 'Piotr', 28, 3);

3. Generate New Project

With that being done, let’s navigate to the Spring Initializr page and generate a new project:

The above configuration is all we need in order to create a fresh Spring Boot 3 project with Kotlin and coroutines. Additionally, in order to connect to the Postgres database, we need two more dependencies: Spring Data R2DBC and PostgreSQL Driver.

With that being done, let’s hit the Generate button and import the project to our IDE (you can find a video on how to configure IntelliJ IDEA for Kotlin right here).

4. Configure R2DBC Connection

Nextly, let’s open up the application.properties file, change its extension to .yaml, and insert the connection config:

spring:
  r2dbc:
    url: r2dbc:postgresql://${DB_HOST:localhost}:5432/
    username: ${DB_USERNAME:postgres}
    password: ${DB_PASSWORD:postgres}

This configuration instructs Spring to check DB_HOST, DB_USERNAME, and DB_PASSWORD environment variables first. If a particular variable is missing, then we provide the default values– localhost and postgres.

5. Create Models

Following, let’s create a new package called model and introduce classes responsible for mapping database tables.

As the first one, let’s implement the Company:

@Table("application.company")
data class Company(
    @Id val id: Long? = null,
    val name: String,
    val address: String
)

The @Table and @Id annotations are pretty descriptive and they are necessary in order to configure mapping in Spring. Nevertheless, it’s worth mentioning that if we do not want to generate identifiers manually, then the identifier fields have to be nullable.

Similarly, let’s create the User data class:

@Table("application.app_user")
data class User(
    @Id val id: Long? = null,
    val email: String,
    val name: String,
    val age: Int,
    val companyId: Long
)

6. CRUD operations using Kotlin Coroutines

Moving forward, let’s create the repository package.

In our project, we will utilize the CoroutineCrudRepository– a dedicated Spring Data repository built on Kotlin coroutines. If you’ve ever been working with Reactor, then in a nutshell, Mono<T> functions are replaced with suspended functions returning the type T, and instead of creating Fluxes, we will generate Flows. On the other hand, if you have never worked with Reactor, then Flow<T> return type means that a function returns multiple asynchronously computed values suspend function returns only a single value.

Of course, this is a simplification and if you would like to learn the differences between Fluxes and Flows, then let me know in the comments.

6.1 Create UserRepository

To kick things off, let’s implement the UserRepository interface:

interface UserRepository : CoroutineCrudRepository<User, Long> {
    
  fun findByNameContaining(name: String): Flow<User>
    
  fun findByCompanyId(companyId: Long): Flow<User>

  @Query("SELECT * FROM application.app_user WHERE email = :email")
  fun randomNameFindByEmail(email: String): Flow<User>
}

The CoroutineCrudRepository extends the Spring Data Repository and requires us to provide two types: the domain type and the identifier type- a User and a Long in our case. This interface comes with 15 already implemented functions, like save, findAll, delete, etc.- responsible for generic CRUD operations. This way, we can tremendously reduce the amount of boilerplate in our Kotlin codebase.

Moreover, we make use of two, great features of Spring Data (which are not Kotlin, or coroutines specific):

• Query Methods, which in simple terms allow us to define queries through function names. Just like above- the findByNameContaining will be translated into where like.. query and  findByCompanyId will let us search users by company identifier.
• @Query, which lets us execute both JPQL and native SQL queries.

Note: I’ve named the third method randomNameFindByEmail just to emphasize, that the function name is irrelevant when using the Query, don’t do that in your codebase 😀

6.2 Add CompanyRepository

Nextly, let’s add the CompanyRepository with only one custom function:

@Repository
interface CompanyRepository : CoroutineCrudRepository<Company, Long> {
    fun findByNameContaining(name: String): Flow<Company>
}

7. Create Services

With model and repository layer implemented, we can move on and create a service package.

7.1 Implement UserService

Firstly, let’s add the UserService to our project:

@Service
class UserService(
    private val userRepository: UserRepository
) {

    suspend fun saveUser(user: User): User? =
        userRepository.randomNameFindByEmail(user.email)
            .firstOrNull()
            ?.let { throw ResponseStatusException(HttpStatus.BAD_REQUEST, "The specified email is already in use.") }
            ?: userRepository.save(user)

    suspend fun findAllUsers(): Flow<User> =
        userRepository.findAll()

    suspend fun findUserById(id: Long): User? =
        userRepository.findById(id)

    suspend fun deleteUserById(id: Long) {
        val foundUser = userRepository.findById(id)

        if (foundUser == null)
            throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")
        else
            userRepository.deleteById(id)
    }

    suspend fun updateUser(id: Long, requestedUser: User): User {
        val foundUser = userRepository.findById(id)

        return if (foundUser == null)
            throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")
        else
            userRepository.save(
                requestedUser.copy(id = foundUser.id)
            )
    }

    suspend fun findAllUsersByNameLike(name: String): Flow<User> =
        userRepository.findByNameContaining(name)

    suspend fun findUsersByCompanyId(id: Long): Flow<User> =
        userRepository.findByCompanyId(id)
}

All the magic starts with the @Service annotation, which is a specialization of a @Component. This way, we simply instruct Spring to create a bean of UserService.

As we can clearly see, our service logic is really straightforward, and thanks to the coroutines we can write code similar to imperative programming.

Lastly, I just wanted to mention the logic responsible for User updates. The save method of the Repository interface works in two ways:

• when the value of a field marked with @Id is set to null, a new entry will be created in the database,
• nevertheless, if the id is not null, then the row with the specified will be updated.

7.2 Create CompanyService

Following, let’s implement the CompanyService responsible for companies management:

@Component
class CompanyService(
    private val companyRepository: CompanyRepository
) {

    suspend fun saveCompany(company: Company): Company? =
        companyRepository.save(company)

    suspend fun findAllCompanies(): Flow<Company> =
        companyRepository.findAll()

    suspend fun findCompanyById(id: Long): Company? =
        companyRepository.findById(id)

    suspend fun deleteCompanyById(id: Long) {
        val foundCompany = companyRepository.findById(id)

        if (foundCompany == null)
            throw ResponseStatusException(HttpStatus.NOT_FOUND, "Company with id $id was not found.")
        else
            companyRepository.deleteById(id)
    }

    suspend fun findAllCompaniesByNameLike(name: String): Flow<Company> =
        companyRepository.findByNameContaining(name)

    suspend fun updateCompany(id: Long, requestedCompany: Company): Company {
        val foundCompany = companyRepository.findById(id)

        return if (foundCompany == null)
            throw ResponseStatusException(HttpStatus.NOT_FOUND, "Company with id $id was not found.")
        else
            companyRepository.save(
                requestedCompany.copy(id = foundCompany.id)
            )
    }

}

8. Implement Controllers

And the last thing we need to implement in our Spring Kotlin Coroutines project are… REST endpoints (and a couple of DTOs 😉 ).

8.1. Create UserResponse and UserRequest

When working in real-life scenarios we can use different approaches, when it comes to serialization and deserialization of data (or in simple terms- JSON <-> Kotlin objects conversions). In some cases dealing with model classes might be sufficient, but introducing DTOs will usually be a better approach. In our examples, we will introduce separate request and response classes, which in my opinion let us maintain our codebase much easier.

To do so, let’s add two data classes to our codebase- the UserRequest and UserResponse (inside the dto package):

data class UserRequest(
    val email: String,
    val name: String,
    val age: Int,
    @JsonProperty("company_id") val companyId: Long
)

data class UserResponse(
    val id: Long,
    val email: String,
    val name: String,
    val age: Int
)

Request classes will be used to translate JSON payload into Kotlin objects, whereas the response ones will do the opposite.

Additionally, we make use of the @JsonProperty annotation, so that our JSON files will use the snake case.

8.2. Implement UserController

With that prepared, we have nothing else to do than create a controller package and implement the UserController:

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

    @PostMapping
    suspend fun createUser(@RequestBody userRequest: UserRequest): UserResponse =
        userService.saveUser(
            user = userRequest.toModel()
        )
            ?.toResponse()
            ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

    @GetMapping
    suspend fun findUsers(
        @RequestParam("name", required = false) name: String?
    ): Flow<UserResponse> {
        val users = name?.let { userService.findAllUsersByNameLike(name) }
            ?: userService.findAllUsers()

        return users.map(User::toResponse)
    }

    @GetMapping("/{id}")
    suspend fun findUserById(
        @PathVariable id: Long
    ): UserResponse =
        userService.findUserById(id)
            ?.let(User::toResponse)
            ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

    @DeleteMapping("/{id}")
    suspend fun deleteUserById(
        @PathVariable id: Long
    ) {
        userService.deleteUserById(id)
    }

    @PutMapping("/{id}")
    suspend fun updateUser(
        @PathVariable id: Long,
        @RequestBody userRequest: UserRequest
    ): UserResponse =
        userService.updateUser(
            id = id,
            requestedUser = userRequest.toModel()
        )
            .toResponse()
}

private fun UserRequest.toModel(): User =
    User(
        email = this.email,
        name = this.name,
        age = this.age,
        companyId = this.companyId
    )

fun User.toResponse(): UserResponse =
    UserResponse(
        id = this.id!!,
        email = this.email,
        name = this.name,
        age = this.age
    )

I know, the class itself might be a little big, but let’s break it down into parts first. We have a couple of annotations here, so why don’t we start with them?

The @RestController is nothing else, then a combination of a @Controller– informing Spring that our class is a web controller and a @ResponseBody- which indicates that the things our functions return should be bound to the web response body (simply- returned to the API user).

The @RequestMapping allows us to specify the path, to which our class will respond. So, each time we will hit the localhost:8080/api/users, Spring will search for a handler function inside this class.

On the other hand, the @PostMapping, @GetMapping, etc. simply indicate for which HTTP methods a particular function should be invoked (and also can take the additional path segments).

Lastly, the @RequestParam, @PathVariable, and @RequestBody are used to map request parameters, segment paths, and body payload to Kotlin class instances.

The rest of the code is responsible for invoking our service methods and throwing meaningful errors when something is wrong (with a help of extension functions used to map between models and responses).

8.3. Implement CompanyResponse and CompanyRequest

Similarly, let’s add response and request classes for Company resources:

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

data class CompanyResponse(
    val id: Long,
    val name: String,
    val address: String,
    val users: List<UserResponse>
)

8.4. Add CompanyController

And this time, let’s add the CompanyController class:

@RestController
@RequestMapping("/api/companies")
class CompanyController(
    private val companyService: CompanyService,
    private val userService: UserService
) {

    @PostMapping
    suspend fun createCompany(@RequestBody companyRequest: CompanyRequest): CompanyResponse =
        companyService.saveCompany(
            company = companyRequest.toModel()
        )
            ?.toResponse()
            ?: throw ResponseStatusException(
                HttpStatus.INTERNAL_SERVER_ERROR,
                "Unexpected error during company creation."
            )

    @GetMapping
    suspend fun findCompany(
        @RequestParam("name", required = false) name: String?
    ): Flow<CompanyResponse> {
        val companies = name?.let { companyService.findAllCompaniesByNameLike(name) }
            ?: companyService.findAllCompanies()

        return companies
            .map { company ->
                company.toResponse(
                    users = findCompanyUsers(company)
                )
            }
    }


    @GetMapping("/{id}")
    suspend fun findCompanyById(
        @PathVariable id: Long
    ): CompanyResponse =
        companyService.findCompanyById(id)
            ?.let { company ->
                company.toResponse(
                    users = findCompanyUsers(company)
                )
            }
            ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "Company with id $id was not found.")

    @DeleteMapping("/{id}")
    suspend fun deleteCompanyById(
        @PathVariable id: Long
    ) {
        companyService.deleteCompanyById(id)
    }

    @PutMapping("/{id}")
    suspend fun updateCompany(
        @PathVariable id: Long,
        @RequestBody companyRequest: CompanyRequest
    ): CompanyResponse =
        companyService.updateCompany(
            id = id,
            requestedCompany = companyRequest.toModel()
        )
            .let { company ->
                company.toResponse(
                    users = findCompanyUsers(company)
                )
            }

    private suspend fun findCompanyUsers(company: Company) =
        userService.findUsersByCompanyId(company.id!!)
            .toList()
}


private fun CompanyRequest.toModel(): Company =
    Company(
        name = this.name,
        address = this.address
    )

private fun Company.toResponse(users: List<User> = emptyList()): CompanyResponse =
    CompanyResponse(
        id = this.id!!,
        name = this.name,
        address = this.address,
        users = users.map(User::toResponse)
    )

And although this controller class looks similar, I wanted to emphasize two things:

• Firstly, thanks to coroutines we don’t have to do any sophisticated mapping, zipping, etc. (known from Reactor) in order to fetch users for each company,
• and secondly- in order to edit Flow elements we use the map intermediate operator, which works just like a map when dealing with collections.

8.5 Create IdNameTypeResponse

As the last thing, I wanted to show you how easily we can merge two Flows. And to do so, let’s introduce a new search endpoint, which will be used to return both users and companies by their names.

So firstly, let’s add the IdNameTypeResponse:

data class IdNameTypeResponse(
    val id: Long,
    val name: String,
    val type: ResultType
)

enum class ResultType {
    USER, COMPANY
}

8.6 Add SearchController

Moving forward, let’s implement the SearchController:

@RestController
@RequestMapping("/api/search")
class SearchController(
  private val userService: UserService,
  private val companyService: CompanyService
) {

  @GetMapping
  suspend fun searchByNames(
    @RequestParam(name = "query") query: String
  ): Flow<IdNameTypeResponse> {
    val usersFlow = userService.findAllUsersByNameLike(name = query)
      .map(User::toIdNameTypeResponse)
    val companiesFlow = companyService.findAllCompaniesByNameLike(name = query)
      .map(Company::toIdNameTypeResponse)

    return merge(usersFlow, companiesFlow)
  }
}

  private fun User.toIdNameTypeResponse(): IdNameTypeResponse =
    IdNameTypeResponse(
      id = this.id!!,
      name = this.name,
      type = ResultType.USER
    )

  private fun Company.toIdNameTypeResponse(): IdNameTypeResponse =
    IdNameTypeResponse(
      id = this.id!!,
      name = this.name,
      type = ResultType.COMPANY
    )

As we can see, in order to combine together both user and company results we can use the merge function. This way, our flows are merged concurrently (and without preserving the order), without limit on the number of simultaneously collected flows.

9. Testing

At this point, we have everything we need to start testing, so let it be your homework. Going through all of the handler methods and preparing appropriate requests will be a great opportunity to recap everything we learned today 🙂

As a bonus- right here you can find a ready-to-go Postman collection, which you can import to your computer.

10. REST API with Spring, Kotlin, coroutines, and Kotlin Flows Summary

And that’s all for this hands-on tutorial, in which we’ve learned together how to create a REST API using Spring, Kotlin, coroutines, and Kotlin Flows. As always, you can find the whole project in this GitHub repository.

If you’re interested in learning more about the reactive approach, then check out my other materials in the Spring Webflux tag.

I hope you enjoyed this article and will be forever thankful for your feedback in the comments section 🙂

The post Reactive REST API With Spring, Kotlin, and Coroutines appeared first on Codersee blog- Kotlin on the backend.

Hello friend! If you see this post, then you are either a regular visitor of my blog or you’ve already received your first 3XX response and realized that it’s time to follow redirects with Spring WebClient 😀

Regardless of the answer, I can assure you that you’ve come to the right place, and after reading this article you will know precisely how to implement a redirect feature with dedicated HttpClient functionality.

Before we start, I just want you to know that although the examples are written in Kotlin, you should be able to this logic regardless of the language used in your Spring Boot / WebFlux project.

2. followRedirect() – a Simple Way to Follow Redirects with Spring WebClient

So let’s start everything by introducing HttpClient’s method- followRedirect()– which we will make use of today. Of course, this is not the only solution to tackle the 3XX response case in Spring WebFlux, but in my opinion, it’s the cleanest way to do so. Moreover, this approach lets us implement our desired logic as a part of the configuration, without polluting the actual business logic.

When we look into the HttpClient implementation, we will spot that the followRedirect() method comes in 6 variants:

HttpClient followRedirect(boolean)
HttpClient followRedirect(boolean, Consumer<HttpClientRequest>)
HttpClient followRedirect(BiPredicate<HttpClientRequest, HttpClientResponse>)
HttpClient followRedirect(boolean followRedirect, BiConsumer<HttpHeaders, HttpClientRequest>)
HttpClient followRedirect(BiPredicate<HttpClientRequest, HttpClientResponse>,BiConsumer<HttpHeaders, HttpClientRequest>)
HttpClient followRedirect(BiPredicate<HttpClientRequest, HttpClientResponse>, Consumer<HttpClientRequest>)

And although these signatures may look scary, you’ll see how simple to implement and useful they are in the upcoming paragraphs.

3. Set Up The Project

As always, let’s start by creating a new Spring Boot project using the Spring Initializr:

As we can see, the only additional dependency we will need today is the Spring Reactive Web. The rest is totally up to you.

Nextly, let’s generate this project and import it to our favorite IDE (like IntelliJ, for example).

4. Configure WebClient and HttpClient

As the next step to properly follow redirects with Spring WebClient, let’s add a Config class:

@Configuration
class Config {

  companion object {
    private const val BASE_URL = "http://localhost:8090"
  }

  @Bean
  fun webClient(httpClient: HttpClient): WebClient =
    WebClient.builder()
      .clientConnector(ReactorClientHttpConnector(httpClient))
      .baseUrl(BASE_URL)
      .build()

  @Bean
  fun httpClient(): HttpClient =
    HttpClient.create()

}

As we can see, we create here the most basic implementation of the WebClient with a base URL set as http://localhost:8090.

[elementor-template id=”9007393″]

5. Create a Service

Nextly, let’s implement the RedirectService responsible for querying particular endpoint:

@Service
class RedirectService(
  private val webClient: WebClient
) {

  fun one(): Mono<ResponseBodyDto> =
    webClient.get()
      .uri("/some-endpoint")
      .header("custom-header", "custom-header-value")
      .header("Authorization", "Bearer value")
      .retrieve()
      .bodyToMono(ResponseBodyDto::class.java)

  data class ResponseBodyDto(val message: String)
}

As we can clearly see, with this implementation we query the http://localhost:8090/some-endpoint with a GET request passing additional custom-header and Authorization headers. The second one is crucial in this tutorial and you’ll know why in the upcoming paragraphs.

Additionally, we expect that the endpoint returns JSON with one item containing a message, which we deserialize into ResponseBodyDto and return as a Mono.

6. Implement Controller

As the next step, let’s add a TestController:

@RestController
@RequestMapping("/test")
class TestController(
private val redirectService: RedirectService
) {

  @GetMapping
  fun one(): Mono<RedirectService.ResponseBodyDto> =
    redirectService.one()

}

As we can see, we expose one GET endpoint, which we will use to test our functionality.

If everything will be working correctly, we should see the 200 OK response with the message when performing GET requests to http://localhost:8080/test.

7. Test Redirect With Default Implementation

Finally, let’s test our functionality. The case is pretty straightforward: each time we perform a GET http://localhost:8090/some-endpoint request, as a response, we get the 301 Status Code without the response body and with Location header set to http://localhost:8090/one-redirect-target.

On the other hand, the http://localhost:8090/one-redirect-target endpoint returns 200 OK with the example message:

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

# Response

Status: 200 OK 
Response Body: Empty

As a result, we received the 200 OK status with an empty response body- definitely not something we would like to see.

To be even more specific, our implementation neither throws an error nor returns the correct value- it ends ups with an empty Mono, which we do not handle.

If you are interested in how to set up a “fake” api, just like the one above, then the answer is Mockoon. Let me know in the comments section if you would be interested in a tutorial about it 😉

8. Make Use of the followRedirect(boolean)

With that being done, let’s finally do something to follow the 301 response in our WebClient.

As the first one, let’s start with the followRedirect(boolean) variant:

@Bean
fun httpClient(): HttpClient =
  HttpClient.create()
    .followRedirect(true)

The only thing we have to do in this case is to pass the true to the followRedirect(boolean) method. Per the documentation:

Specifies whether HTTP status 301|302|303|307|308 auto-redirect support is enabled.

So this time, our implementation will follow the redirect properly when any of the above status codes is returned. Moreover, if we check in Mockoon, we will see that both the custom and Authorization headers are present.

But here comes the catch- the sensitive headers:

• Expect,
• Cookie,
• Authorization,
• Proxy-Authorization,

are only added when redirecting to the same domain! When testing locally, when we simply change the port of a redirected resource from 8090 to another, we will see that the Authorization header is missing.

9. followRedirect- Add Sensitive Headers

OK, so what possibility do we have if we would like to handle redirects to different domains and re-add the same headers?

Well, if this is the only thing we would like to do, then let’s make use of the HttpClient followRedirect(boolean followRedirect, BiConsumer<HttpHeaders, HttpClientRequest>) implementation:

@Bean
fun httpClient(): HttpClient =
  HttpClient.create()
    .followRedirect(true) { headers, request ->
      request.headers(headers)
    }

As we can see, this method lets us use the HTTP headers we sent in our first request.

We can simply add all of them, just like above, or only specific ones. Either way- please be cautious with this approach to not leak users’ tokens.

10. Print Redirect Request Info

But what if we don’t necessarily want to access the headers and simply want to log the redirect request information, or add another header?

Well, in such a case I would recommend the HttpClient followRedirect(boolean, Consumer<HttpClientRequest>):

@Bean
fun httpClient(): HttpClient =
  HttpClient.create()
    .followRedirect(true) { redirectRequest ->
      println("URI: ${redirectRequest.uri()}")
      println("Is follow redirect: ${redirectRequest.isFollowRedirect}")
      println("Redirected from: ${redirectRequest.redirectedFrom().firstOrNull()}")
      println("Resource URL: ${redirectRequest.resourceUrl()}")
      redirectRequest.addHeader("another-header", "another-value")
      println("Request headers: ${redirectRequest.requestHeaders()}")
    }

This variant allows us to pass a HttpClientRequest Consumer. As we can see above the instance of HttpClientRequest contains useful info, like:

• redirect URI,
• whether the request is following the redirect,
• previous redirections array (as there might be multiple),
• the URL we are going to query now,
• all headers of the upcoming request.

Additionally, with this one, we can set more headers- just like above.

If we run the test now, we should see something like that:

URI: /one-redirect-target
Is follow redirect: true
Redirected from: http://localhost:8090/some-endpoint
Resource URL: http://localhost:8091/one-redirect-target
Request headers: DefaultHttpHeaders[user-agent: ReactorNetty/1.0.23, host: localhost:8091, accept: */*, custom-header: custom-header-value, another-header: another-value]

11. Follow Redirect Only When Conditions Are Met

Lastly, let’s see what can we do to add custom logic checking whether the request should be followed, or not.

As I’ve mentioned earlier, the default implementation enables auto-redirect for the following status codes: 301|302|303|307|308.

If we would like to change this behavior, then the HttpClient followRedirect(BiPredicate<HttpClientRequest, HttpClientResponse>) implementation is a great choice:

@Bean
fun httpClient(): HttpClient =
  HttpClient.create()
    .followRedirect { clientRequest, clientResponse ->
      clientRequest.requestHeaders().contains("custom-header")
        && clientResponse.status().code() == 301
    }

As we can see, the request we will follow the redirect only when our request contains a custom-header header and the response status code is 301.

12. Follow Redirects With Spring WebClient

And that would be all for this article on how to follow redirects (3xx) responses with Spring WebClient.

Together, we learned how to implement such functionality and make use of different implementations shipped with Spring. Please keep in mind that there are two more methods, which I haven’t covered because they basically combine the logic I have shown (but still, they may suit your use-case better).

Finally, if you think this content is useful, or I helped you, then please leave a comment– that helps me to reach an even bigger audience. And as always- you can find the GitHub repository with the source code right here.

The post How To Follow Redirects (3XX) With Spring WebClient? appeared first on Codersee blog- Kotlin on the backend.

If you are not sure, whether this is something for you, then please check the introduction, which will help you to make the decision:

If you would like to see the course, then you can find all videos in this playlist.

This is my first YouTube course and I will be forever thankful if you would like to share some feedback with me. You can do that in the comments section here, under the video, or by using the contact form. I am constantly trying to improve the content quality, but that’s simply impossible without hearing from you and your perspective 🙂

Let me know what you think about this course and what topics would you like to see after Spring WebFlux.

Finally, I wanted to share that Codersee was announced as one of the Top 10 Kotlin Programming Blogs on the web by FeedSpot. On this occasion, I would like to thank you, dear reader, for your input and for being a part of this journey. Thanks and see you in the near future! 🙂

The post YouTube Course On REST API With Spring WebFlux and Kotlin appeared first on Codersee blog- Kotlin on the backend.

In this short article, I would like to show you how to configure Flyway when working with Spring WebFlux and Spring Data R2DBC.

In my previous tutorial, we’ve learned a lot about Flyway itself and how to set it up correctly, when working with Spring Boot. Nevertheless, if we would like to apply this knowledge when building a reactive web application with Spring WebFlux and Spring Data R2DBC, we would have to take a different approach. And that’s what we are going to focus on in this tutorial.

2. Imports

2.1. Create Spring WebFlux With R2DBC Project

As the first step, let’s create a skeleton project. We can do so by simply going to the Spring Initializr page and selecting the following dependencies:

• Spring Reactive Web
• Spring Data R2DBC
• PostgreSQL Driver

After that, we should see the following in our build.gradle.kts file:

implementation("org.springframework.boot:spring-boot-starter-data-r2dbc")
implementation("org.springframework.boot:spring-boot-starter-webflux")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
runtimeOnly("org.postgresql:postgresql")
runtimeOnly("org.postgresql:r2dbc-postgresql")

// other dependencies

2.2. Add Flyway Dependency

Unfortunately, we can’t add the Flyway dependency to our Spring WebFlux project on the same page, so we have to do it manually:

implementation("org.flywaydb:flyway-core:8.5.11")

With that being done, we have to reload Gradle changes and wait till the additional dependency is fetched to our environment.

3. Configure application.properties (or YAML) File

As the next step, let’s head to the application.properties file (or application.yaml in my case) and configure database connection along with Flyway:

spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/
    username: postgres
    password: password
  flyway:
    url: jdbc:postgresql://localhost:5432/
    user: postgres
    password: password

Please keep in mind that the values used for port, username, and password may be different in your case. Moreover, in the case of the Flyway connection, we have to use JDBC.

4. Implement Flyway Migration

Nextly, let’s prepare an SQL file, which we would like to run as the first migration. Let’s call it V1__My_First_Migration.sql:

CREATE TABLE person(
  id SERIAL NOT NULL PRIMARY KEY,
  email TEXT NOT NULL
);

As we can see, this simple script will create a new table called person. Please remember to put this file in the correct directory- resources/db/migration/ in our case.

5. Add Flyway Configuration For R2DBC

As the next step, let’s run our application to see if our Flyway migration is working. Technically, the app started successfully. Nevertheless, logs do not contain anything about applied migration and when we check the database we can clearly see, that migration was not run.

To change that, let’s add a FlywayConfiguration file to our project:

@Configuration
class FlywayConfiguration(private val env: Environment) {

    @Bean(initMethod = "migrate")
    fun flyway(): Flyway {
        return Flyway(Flyway.configure()
            .dataSource(
                env.getRequiredProperty("spring.flyway.url"),
                env.getRequiredProperty("spring.flyway.user"),
                env.getRequiredProperty("spring.flyway.password"))
        )
    }
}

Alternatively, we can use @Value annotation, as well:

@Configuration
class FlywayConfiguration(
    @Value("\${spring.flyway.url}") private val url: String,
    @Value("\${spring.flyway.user}") private val user: String,
    @Value("\${spring.flyway.password}") private val password: String
) {

    @Bean(initMethod = "migrate")
    fun flyway(): Flyway {
        return Flyway(
            Flyway.configure()
                .dataSource(url, user, password)
        )
    }
}

As we can see, this configuration is responsible for creating a new Flyway bean with the URL, username, and password obtained from our application.yaml file.

If we rerun our app once again, we will see the following:

Creating Schema History table "public"."flyway_schema_history" ...
Current version of schema "public": << Empty Schema >>
Migrating schema "public" to version "1 - My First Migration"
Successfully applied 1 migration to schema "public", now at version v1 (execution time 00:00.034s)

The above message clearly indicates that the migration was run and we can expect a new table in our database.

6. Summary

And that would be all for this short article on how to configure Flyway migrations with Spring WebFlux and R2DBC.

Let me know if you found this material useful in the comment sections below, or by using the contact form.

Finally, if you would like to see the whole source code, please refer to this GitHub repository.

The post Flyway Migrations With Spring WebFlux (R2DBC) appeared first on Codersee blog- Kotlin on the backend.

In the previous article, we’ve covered the basic differences between Mono.just(), defer(), fromSupplier() and create() methods. If you haven’t seen it yet, I highly recommend you to take a while and check it out.

Although we’ve spent quite some time trying to understand the behavior and possible use cases for each method, it’s worth to mention that we focused on successful cases. Unfortunately, this is not always the case in real-life scenarios. Provided that, in this article we will focus on how the mentioned methods vary in exceptions and null handling and what should we be aware of.

2. Imports

As the first step, let’s import the necessary library to our project:

implementation("io.projectreactor:reactor-core:3.4.12")

3. Null Handling

After that, we can start can start practicing with nulls, also known as The Billion Dollar Mistake. Even though the Kotlin provides us a great support in null prevention, they can still occur- either on purpose (hopefully), or by mistake.

Given that, let’s prepare a function called nullReturningDateFetching:

private fun nullReturningDateFetching(): LocalDateTime? {
    Thread.sleep(500)
    println("GETTING DATE")
    return null
}

As a word of explanation- we expect that the above code will cause the current thread to sleep, following by printing GETTING DATE and returning a null value.

3.1. Mono.just()

As the next step, let’s start with the Mono.just() method- just like in the previous article:

private fun monoJustNull(): Mono<LocalDateTime> =
    Mono.just(nullReturningDateFetching())

fun monoJustNullSubscription() {
    val myMono = monoJustNull()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

fun monoJustNullInstantiation() {
    val myMono = monoJustNull()
}

And let’s run both methods:

// monoJustNullSubscription
GETTING DATE
Exception in thread "main" java.lang.NullPointerException: value

// monoJustNullInstantiation
GETTING DATE
Exception in thread "main" java.lang.NullPointerException: value

As we can clearly see, both cases completed with the same result- thrown NullPointerException. Whatsoever, if we used an IDE, like IntelliJ, it warned us about type mismatch! The reason behind that is pretty straightforward- internally, the Mono.just() method creates a MonoJust class instance, which requires a constructor argument to be not-null.

Additionally, we can’t implement any callback behavior using error-handling operators, like onErrorReturn(). The only possibility to recover in this case would be to wrap the Mono.just(nullReturningDateFetching()) with a try-catch block and personally, I find this solution a bit ugly.

Thankfully, if we really need to use the Mono.just() and the value we would like to wrap can be null, a Mono class ships with the justOrEmpty() method. Instead of throwing exception, it will emit an onComplete signal, which we can fallback with, for instance, defaultIfEmpty().

3.2. Mono.defer()

As the next example, let’s figure out how does the Mono.defer() works:

Note: the following examples will focus on the subscription part- the reason for this has been covered in the previous article.

fun monoDeferNull(): Mono<LocalDateTime> =
    Mono.defer { null }
 
fun monoDeferSubscription() {
    val myMono = monoDeferNull()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

Nextly, let’s check the result:

// monoDeferSubscription
// 3x:
[ERROR] (main) Operator called default onErrorDropped - reactor.core.Exceptions$ErrorCallbackNotImplemented: 
java.lang.NullPointerException: The Mono returned by the supplier is null
reactor.core.Exceptions$ErrorCallbackNotImplemented: java.lang.NullPointerException: The Mono returned by the supplier is null
Caused by: java.lang.NullPointerException: The Mono returned by the supplier is null

As we might have noticed, the exception seems to be exactly the same. However, it has been caught internally and propagated into the onError signal. For that reason, the number of messages is equal to the number of Subscribers we’ve created.

Let’s take a while to see what happens underneath:

try {
    p = Objects.requireNonNull(supplier.get(),
            "The Mono returned by the supplier is null");
}
catch (Throwable e) {
    Operators.error(actual, Operators.onOperatorError(e, actual.currentContext()));
    return;
}

We can clearly spot, that this code is responsible for the message we’ve received. The Operators.error itself is responsible for calling the onError method of our Subscribers.

On the positive side, this behavior allows us to recover with some error-handling operator, like:

fun monoDeferSubscriptionRecover() {
    val myMono =
            monoDeferNull()
                .onErrorReturn(LocalDateTime.MIN)

    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}
// Result:
-999999999-01-01T00:00
-999999999-01-01T00:00
-999999999-01-01T00:00

3.3. Mono.fromSupplier()

Nextly, let’s check the Mono.fromSupplier() method:

fun monoFromSupplierNull(): Mono =
    Mono.fromSupplier { nullReturningDateFetching() }

fun monoFromSupplierSubscription() {
    val myMono = monoFromSupplierNull()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

Similarly, let’s see the result:

// monoFromSupplierSubscription
GETTING DATE
GETTING DATE
GETTING DATE

This time, no exception has been thrown. In practice, the fromSupplier() method just completes empty when the provided Supplier ( nullReturningDateFetching() in our case) resolves to null. Although we got rid of exception, we need to be aware of that and handle it accordingly. Indeed, the Mono class ships with defaultIfEmpty method, which could be used here.

3.3. Mono.create()

As the last example of null handling, let’s see the Mono.create() behavior:

private fun monoCreateNull(): Mono =
    Mono.create { monoSink -> monoSink.success(nullReturningDateFetching()) }

fun monoCreateNullSubscription() {
    val myMono = monoCreateNull()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

And again, let’s run the above code:

// monoCreateNullSubscription
GETTING DATE
GETTING DATE
GETTING DATE

As we can see, result itself is exactly the same, as in the previous example. However, the reason is slightly different and pretty well explained in the documentation itself:

Calling this method [ success(T) ] with a null value will be silently accepted as a call to success() by standard implementations.

As a result, the silently accepted success() call completes without any value.

3. Exceptions Handling

With all of that being explained, we can finally focus on their differences in exceptions handling.

Just like previously, let’s start with another date fetching variant, called exceptionDateFetching:

private fun exceptionDateFetching(): LocalDateTime {
    Thread.sleep(500)
    println("GETTING DATE")
    throw RuntimeException("ERRORS HAPPEN")
}

Unlike the previous paragraph, let’s perform a collective comparison of all methods:

private fun monoJustException(): Mono<LocalDateTime> =
Mono.just(exceptionDateFetching())

private fun monoDeferException(): Mono<LocalDateTime> =
    Mono.defer { monoJustException() }

private fun monoFromSupplierException(): Mono<LocalDateTime> =
    Mono.fromSupplier { exceptionDateFetching() }

private fun monoCreateException(): Mono<LocalDateTime> =
    Mono.create { monoSink -> monoSink.success(exceptionDateFetching()) }

After running all of them, we should see the following result:

// monoJustExceptionSubscription
GETTING DATE
Exception in thread "main" java.lang.RuntimeException: ERRORS HAPPEN

// monoDeferExceptionSubscription & monoFromSupplierExceptionSubscription & monoCreateExceptionSubscription
// 3x
GETTING DATE
[ERROR] (main) Operator called default onErrorDropped - reactor.core.Exceptions$ErrorCallbackNotImplemented: 
java.lang.RuntimeException: ERRORS HAPPEN
reactor.core.Exceptions$ErrorCallbackNotImplemented: java.lang.RuntimeException: ERRORS HAPPEN
Caused by: java.lang.RuntimeException: ERRORS HAPPEN

As we can see- when using the Mono.just() method, we have to explicitly make sure that all exceptions are handled within the function responsible for date-time creation. Without that, the exception will be thrown on the instantiation and lead to thread termination.

On the other hand, the rest of the methods will log an error and finally, throw it via Exceptions.bubble(Throwable). In other words, the exception will be again caught internally and propagated as an onError signal. As we have already seen, this type of signal might be pretty easily handled with onError* methods.

5. Summary

And that would be all for this article. I really hope, that you will benefit from this, and the previous tutorial describing differences between the Mono.just(), defer(), fromSupplier() and create() methods. Although the Project Reactor is not the most trivial thing in the world, I am 100% sure that you can take advantage of learning it. It will be a pleasure to me to walk you through this process.

Finally, just like always, you can find the source code here. Moreover, if you would like to ask about anything or you have some suggestions about future topics, please let me know about it in the comment section below, or by using the contact form.

If you find this material useful, you might be interested in my previous articles:

• What is Kotlin and Why Should You Learn It?
• Mono.just() vs defer() vs fromSupplier() vs create() – Part 1
• Micronaut with MongoDB and Kotlin

The post Mono.just() vs defer() vs fromSupplier() vs create() – Part 2 appeared first on Codersee blog- Kotlin on the backend.

In the first article of a series related to the Project Reactor, I would like to show you the process of creating Monos with Mono.just(), Mono.defer(), Mono.fromSupplier() and Mono.create() methods. After this step by step tutorial, you will have a decent understanding of each method and differences between them.

Nonetheless, this is not an introduction to the Project Reactor and to get the most out of this article, you need to understand at least the basic concepts associated with it. Considering that, I highly recommend their official docs, but if you would be interested in a video explanation, please let me know in the comments section below.

As the last thing in the introduction I would like welcome you to the Codersee after a long period of time. Last 12 months have been a pretty tough time for me and I had to suspend all of my blog activities. Nevertheless, I am back to blogging bringing you new portion of knowledge and ideas. I am so excited about upcoming months and really hope that you will be too.

2. Eager vs Lazy Evaluation

Before we start considerations about Mono creation, let’s take a while to understand the difference between eager and lazy evaluation. In general, both terms describe the way expressions are evaluated. With eager evaluation, the value will be evaluated immediately, when the instruction has been encountered. In the second case, the process will be delayed until the value is really needed, hence the term- lazy evaluation.

[elementor-template id=”9007393″]

3. Hot vs Cold Publishers

Another terms I would like to cover before heading to the clue of this article are hot and cold publishers. In Project Reactor all Publishers (like Monos or Fluxes) are considered either one of them. Cold publishers, generate new data for each subscription (consider it a bit similar to lazy evaluation), whereas hot publishers are independent of subscribers and will produce data anyway (similarity to eagerness).

Undoubtedly, the two above paragraphs are just a brief summary and I highly recommend you do a further investigation. However, I am pretty sure that this knowledge will be sufficient for the purpose of this tutorial.

4. Imports

With that being said, let’s start by importing necessary library to our project:

implementation("io.projectreactor:reactor-core:3.4.12")

Note: you can find the source code for this article, as always, in our GitHub repository.

5. Create Monos

After that, let’s define what exactly a Mono is in terms of Project Reactor? Well, it’s nothing else than just a specialized Publisher capable of asynchronous emitting of either 1 or 0 element. Fluxes, on the other hand, represent an asynchronous sequence of 0 to N elements.

4.1. Mono.just()

Provided that, let’s start everything with an example function called successfulDateFetching:

fun successfulDateFetching(): LocalDateTime {
    Thread.sleep(500)
    println("GETTING DATE")
    return LocalDateTime.now()
}

As we can see, it will be responsible for three things:

• causing the currently executing thread to sleep,
• printing the text to the output,
• and finally, returning the current date-time information from the system clock

As the next step, let’s let’s implement the following Mono.just() example:

fun monoJust(): Mono<LocalDateTime> =
    Mono.just(successfulDateFetching())

fun monoJustSubscription() {
    val myMono = monoJust()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

fun monoJustInstantiation() {
    val myMono = monoJust()
}

The above code is responsible for creating a new Mono inside the monoJust function and after that it’s utilized inside the monoJustSubscription or monoJustInstantiation methods. Given that, it’s worth to quote the Reactor documentation here:

Nothing Happens Until You subscribe()

And that’s one of the most important things when dealing with Reactor- data do not start pumping into by default. By creating a Mono, we’re just defining an asynchronous process, but all the magic happens when we tie it to a Subscriber. Personally, I would compare that to the process of class definition– just like a class is a simple skeleton with some predefined behavior until we create it’s instance, so here a Mono defines the process of data flow until we subscribe to it.

Note: As always, I highly encourage you to copy and run all of the examples manually, so that you could get the most out of this article.

With that being said, we expect that that a date-time information will be printed 3 times after running monoJustSubscription and nothing happen in second scenario. Let’s validate if it’s true:

// monoJustSubscription
GETTING DATE
2021-12-08T07:58:22.053724500
2021-12-08T07:58:22.053724500
2021-12-08T07:58:22.053724500

// monoJustInstantiation
GETTING DATE

As you might have noticed- the result seems to be a bit odd. Why are the printed values exactly the same in the first case and why does the GETTING DATE has been even printed without subscription?

Basically, this is the main difference between a Mono.just() and the rest of the methods we’ll compare in this article. It is a hot publisher and the value has been captured at the instantiation time. In fact, the successfulDateFetching() has been invoked when we created and instance of Mono- even if we didn’t subscribe to it! Undeniably, we should be aware of this behavior especially when dealing with multiple subscribers.

4.2. Mono.defer()

Thankfully, Mono.just() is not the only possible way of creating Monos. Let’s see what can we do to delay the process of obtaining the date-time with Mono.defer():

fun monoDefer(): Mono<LocalDateTime> =
    Mono.defer { monoJust() }

fun monoDeferSubscription() {
    val myMono = monoDefer()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

fun monoDeferInstantiation() {
    val myMono = monoDefer()
}

After that, let’s run the examples and see the result:

// monoDeferSubscription
GETTING DATE
2021-12-08T09:01:56.457742200
GETTING DATE
2021-12-08T09:01:56.970125600
GETTING DATE
2021-12-08T09:01:57.487761200

// monoDeferInstantiation 

This time, we’ve achieved a real laziness- a successfulDateFetching() was triggered each time a new Subscriber was registered. Moreover, nothing happened, when we just instantiated a Mono. The reason behind this is pretty straightforward- Mono.defer() will supply a target Mono (created by the monoJust(), in our case) to each Subscriber. In fact, the delay between each subscription could be extended to whatever value we would like to, and the printed date-time would be up to date each time.

At this point, we can clearly see that these two methods serve different purposes. If we are dealing with some constant data, or data set, or we are just OK with the data being obtained eagerly, then the Mono.just() should be the choice. On the other hand, if we want the subscriber to receive data calculated at the time of subscription, then the Mono.defer() should be picked to “wrap” another Mono.

4.3. Mono.fromSupplier()

Similarly to defer(), we can delay the data evaluation with Mono.fromSupplier() case. As the documentation states, it allows us to:

Create a Mono, producing its value using the provided Supplier. If the Supplier resolves to null, the resulting Mono completes empty.

Given that’s let’s see the following example:

private fun monoFromSupplier(): Mono<LocalDateTime> =
    Mono.fromSupplier { successfulDateFetching() }

fun monoFromSupplierSubscription() {
    val myMono = monoFromSupplier()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

fun monoFromSupplierInstantiation() {
    val myMono = monoFromSupplier()
}

In this case, the output presents as follows:

// monoFromSupplierSubscription
GETTING DATE
2021-12-08T08:33:59.168426800
GETTING DATE
2021-12-08T08:33:59.671269400
GETTING DATE
2021-12-08T08:34:00.187244300

// monoFromSupplierInstantiation

We can clearly spot that this, and Mono.defer() execution worked exactly the same. As a word of explanation- both methods serve us to delay (defer) the moment of capturing the value. Most of the time, we ill lean toward them when dealing with external libraries, or another part of the code that we do not have an influence on. To put it simple, our choice will be:

• Mono.defer()– when dealing with another library, method or whatever else returning a Mono instance
• Mono.fromSupplier()– when consuming a simple value being returned from external (not a Mono)

Additionally, it’s worth mentioning that Project Reactor ships with another method called fromCallable(), which you might be interested in, as well (but considerations on Supplier and Callable usage won’t be a part of this article).

4.3. Mono.create()

Lastly, let’s have a look at Mono.create(). Despite it’s simple name it is the most advanced way of creating Monos covered in this article. Again, I highly recommend you to check out the official documentation for more thorough exaplanation and examples.

As a word of clarification- Mono.create() allows us to deal with internal Mono signals through the MonoSink<T> wrapper’s create(), create(T) and error(Throwable) methods. Similarly, it creates a deffered emitter, I believe the result of the following example is just a formality:

fun monoCreate(): Mono =
    Mono.create { monoSink ->
        monoSink.success(successfulDateFetching())
    }

fun monoCreateSubscription() {
    val myMono = monoCreate()
    myMono.subscribe(::println)
    myMono.subscribe(::println)
    myMono.subscribe(::println)
}

fun monoCreateInstantiation() {
    val myMono = monoCreate()
}

// #Result
// monoCreateSubscription
// GETTING DATE 2021-12-08T08:33:59.168426800
// GETTING DATE 2021-12-08T08:33:59.671269400 
// GETTING DATE 2021-12-08T08:34:00.187244300 

// monoCreateInstantiation

As we might have noticed, the instantiation process is deferred here, just like when dealing with defer() and fromSupplier() methods. Nevertheless, it is the most advanced method presented in this tutorial which gives us much more control over emitted values and in most cases- it’s usage won’t be necessary. On the other hand, it might be a great choice when dealing with some callback-based APIs.

5. Conclusion on Mono.just() vs defer() vs fromSupplier() vs create()

Finally, let’s have a quick recap on Mono.just() vs defer() vs fromSupplier() vs create():

• Mono.just()– value captured at the time of instantiation, each Subscriber will receive the same value
• Mono.defer()– supplies a target Mono to each Subscriber, so the value will be obtained when subscribing
• Mono.fromSupplier()– produces a value using provided subscriber on subscribe
• Mono.create()– creates a deferred emitter, the most advanced method allowing to operate on MonoSink<T>

6. Summary

And that’s all for the first article describing differences between Mono’s just(), defer(), fromSupplier() and create() methods. Additionally, in the next episode, we will focus on differences in null and exceptions handling.

Finally, I really hope that after this read you’ll get a better understanding of their behavior and use cases. For the source code, please refer to this GitHub repository. Moreover, if you would like to ask about anything or need some more explanation, please do it in the comment section below, or by using the contact form.

The post Mono.just() vs defer() vs fromSupplier() vs create() – Part 1 appeared first on Codersee blog- Kotlin on the backend.

In today’s article, I would like to walk you step by step through the process of creating a reactive MongoDB REST API CRUD with Spring Boot and Kotlin.

Reactive programming is becoming more and more popular nowadays and plenty of projects incorporated the Spring WebFlux framework, which provides support for creating non-blocking web applications. The reactive approach has plenty of advantages and I personally believe every programmer should know it, at least at a basic level. However, we need to keep in mind, that it is not the Golden Bullet and for some projects, the well-known Spring Web MVC will be a better choice.

After finishing this tutorial, you will be able to create a simple Spring Boot REST API CRUD and connect it to the MongoDB with Spring Data Reactive MongoDB (if you’d like to see how to connect to the MongoDB in a standard Web MVC application, please see my previous article). Additionally, if this is your first meeting with the WebFlux or Project Reactor, I highly encourage you to check out this article covering the basics.

2. Run MongoDB Server

Just like in the previous article, 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                  CREATED             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. Imports

As the next step, let’s create a Spring Boot project and add necessary imports (I highly encourage you to use the Spring Initializr when doing that):

implementation("org.springframework.boot:spring-boot-starter-data-mongodb-reactive")
implementation("org.springframework.boot:spring-boot-starter-webflux")
implementation("io.projectreactor.kotlin:reactor-kotlin-extensions")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
testImplementation("io.projectreactor:reactor-test")

4. Configure Application Properties

After we’ve configured the imports, let’s add an additional configuration to the application.yaml file:

server:
  error:
    include-message: always

Since the Spring Boot 2.3 release, error messages are no longer included in the server’s responses by default. In this guide, I would like to show you how to create a custom exception class with a message, so these 3 lines are necessary.

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:

@Document("companies")
data class Company(
    @Id
    val id: String? = null,
    var name: String,
    @Field("company_address")
    var address: String
)

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

As you might have noticed, the Company class definition has two (optional) annotations more, than the Employee. Let me explain them:

• a @Document annotation- usually, we will use it to change the default name of the MongoDB collection used to store the document. By default, the name of the collection will be the class name changed to start with a lower-case letter. So, in our database, we will have two collections created: the companies and the employee.
• a @Field annotation- it’s used to define custom metadata for the document fields, like a key name, order, or a target type. In our example, we’ve changed the key name from the default “address” to the “company_address”.

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. From the Spring Boot perspective, we can treat them as ObjectIds or Strings– the decision is up to you.

6. Add Custom Exception

Nextly, let’s create a custom exception class named NotFoundException:

@ResponseStatus(HttpStatus.NOT_FOUND)
class NotFoundException(msg: String) : RuntimeException(msg)

The @ResponseStatus annotation allows us to specify the status code to use for the response- in this case- 404 Not Found.

7. Create Repositories

As the next step, let’s create repositories for our data. Let’s start by adding the CompanyRepository first:

interface CompanyRepository : ReactiveMongoRepository<Company, String>

As you can see, the CompanyRepository interface extends the ReactiveMongoRepository, which provides us with basic CRUD operations (and of course a reactive support, as well). Similarly, let’s create the EmployeeRepository:

interface EmployeeRepository : ReactiveMongoRepository<Employee, ObjectId> {
    fun findByCompanyId(id: String): Flux<Employee>
}

This time, we’ve provided additionally the definition of findByCompanyId function, which will be used later to find employees of a specific company.

If you have any prior experience with Spring Data repositories, you might have noticed the crucial difference between the standard and reactive repositories- they are using Fluxes and Monos, instead of Objects and Collections.

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. Please don’t worry, if anything is confusing to you, I’ll cover all functions later.

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

    fun createCompany(request: CompanyRequest): Mono<Company> =
        companyRepository.save(
            Company(
                name = request.name,
                address = request.address
            )
        )

    fun findAll(): Flux<Company> =
        companyRepository.findAll()

    fun findById(id: String): Mono<Company> =
        companyRepository.findById(id)
            .switchIfEmpty {
                Mono.error(
                    NotFoundException("Company with id $id not found")
                )
            }

    fun updateCompany(id: String, request: CompanyRequest): Mono<Company> =
        findById(id)
            .flatMap {
                companyRepository.save(
                    it.apply {
                        name = request.name
                        address = request.address
                    }
                )
            }
            .doOnSuccess { updateCompanyEmployees(it).subscribe() }

    fun deleteById(id: String): Mono<Void> =
        findById(id)
            .flatMap(companyRepository::delete)

    private fun updateCompanyEmployees(updatedCompany: Company): Flux<Employee> =
        employeeRepository.saveAll(
            employeeRepository.findByCompanyId(updatedCompany.id!!)
                .map { it.apply { company = updatedCompany } }
        )
}

Let’s start with the two easiest functions:

fun createCompany(request: CompanyRequest): Mono<Company> =
    companyRepository.save(
        Company(
            name = request.name,
            address = request.address
        )
    )

fun findAll(): Flux<Company> =
    companyRepository.findAll()

They are responsible for creating and querying all companies, but instead of returning elements, they wrap them into Mono and Flux, which can be processed later.
What about a findById function?

fun findById(id: String): Mono<Company> =
    companyRepository.findById(id)
        .switchIfEmpty {
            Mono.error(
                NotFoundException("Company with id $id not found")
            )
        }

The findById function from CompanyRepository returns a Mono with the existing data or an empty Mono in case if no data has been found. You might think about it as something similar to the Optional in Java. So in our case, if we would like to “throw” the exception, we need to create a new Mono instance with our Throwable- the NotFoundException object and pass it to the switchIfEmpty function.

Nextly, let’s check the updateCompany function:

fun updateCompany(id: String, request: CompanyRequest): Mono<Company> =
        findById(id)
            .flatMap {
                companyRepository.save(
                    it.apply {
                        name = request.name
                        address = request.address
                    }
                )
            }
            .doOnSuccess { updateCompanyEmployees(it).subscribe() }

private fun updateCompanyEmployees(updatedCompany: Company): Flux<Employee> =
    employeeRepository.saveAll(
        employeeRepository.findByCompanyId(updatedCompany.id!!)
            .map { it.apply { company = updatedCompany } }
    )

Firstly, it invokes the findById function to get the Mono object of the desired company. After that, we use the flatMap to transform the value emitted by it (the company) asynchronously and return the value emitted by the save method. If everything executed successfully, the updateCompanyEmployees function will be invoked. As the last step, we need to subscribe to the Flux returned from this function.

8.2. MongoDB Relations

You might be wondering why do we need to update all employees connected with the company, each time we are updating 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 relations, please let me know and I will create another tutorial about it :).

As the last step, let’s check the deleteById function:

fun deleteById(id: String): Mono<Void> =
    findById(id)
        .flatMap(companyRepository::delete)

All it does is to fetch the company’s Mono and delete its value returning the instance of Mono<Void>.

8.3. Create EmployeeService

Similarly, let’s create the EmployeeRequest responsible for data handling and EmployeeService:

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

@Service
class EmployeeService(
    private val companyService: CompanyService,
    private val employeeRepository: EmployeeRepository
) {

    fun createEmployee(request: EmployeeRequest): Mono<Employee> {
        val companyId = request.companyId

        return if (companyId == null) {
            createEmployeeWithoutCompany(request)
        } else {
            createEmployeeWithCompany(companyId, request)
        }
    }

    private fun createEmployeeWithoutCompany(request: EmployeeRequest): Mono<Employee> {
        return employeeRepository.save(
            Employee(
                firstName = request.firstName,
                lastName = request.lastName,
                email = request.email,
                company = null
            )
        )
    }

    private fun createEmployeeWithCompany(companyId: String, request: EmployeeRequest) =
        companyService.findById(companyId)
            .flatMap {
                employeeRepository.save(
                    Employee(
                        firstName = request.firstName,
                        lastName = request.lastName,
                        email = request.email,
                        company = it
                    )
                )
            }

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

    fun findAllByCompanyId(id: String): Flux<Employee> =
        employeeRepository.findByCompanyId(id)

    fun findById(id: ObjectId): Mono<Employee> =
        employeeRepository.findById(id)
            .switchIfEmpty {
                Mono.error(
                    NotFoundException("Employee with id $id not found")
                )
            }

    fun updateEmployee(id: ObjectId, request: EmployeeRequest): Mono<Employee> {
        val employeeToUpdate = findById(id)

        val companyId = request.companyId
        return if (companyId == null) {
            updateEmployeeWithoutCompany(employeeToUpdate, request)
        } else {
            updateEmployeeWithCompany(companyId, employeeToUpdate, request)
        }
    }

    private fun updateEmployeeWithoutCompany(employeeToUpdate: Mono, request: EmployeeRequest) =
        employeeToUpdate.flatMap {
            employeeRepository.save(
                it.apply {
                    firstName = request.firstName
                    lastName = request.lastName
                    email = request.email
                    company = null
                }
            )
        }

    private fun updateEmployeeWithCompany(
        companyId: String,
        employeeToUpdate: Mono,
        request: EmployeeRequest
    ) =
        companyService.findById(companyId)
            .zipWith(employeeToUpdate)
            .flatMap {
                employeeRepository.save(
                    it.t2.apply {
                        firstName = request.firstName
                        lastName = request.lastName
                        email = request.email
                        company = it.t1
                    }
                )
            }

    fun deleteById(id: ObjectId): Mono<Employee> {
        return findById(id)
            .flatMap(employeeRepository::delete)
    }
}

After implementing the previous chapter, most of the concepts used in the code above should be familiar to you, so I won’t be diving into the details here. However, you might be interested in what exactly the zipWith function does inside the updateEmployeeWithCompany?

private fun updateEmployeeWithCompany(
    companyId: String,
    employeeToUpdate: Mono<Employee>,
    request: EmployeeRequest
) =
    companyService.findById(companyId)
        .zipWith(employeeToUpdate)
        .flatMap {
            employeeRepository.save(
                it.t2.apply {
                    firstName = request.firstName
                    lastName = request.lastName
                    email = request.email
                    company = it.t1
                }
            )
        }

Well, the zipWith function combines the result of two Monos into a Tuple2 (a data structure holding two, non-null values). In our case, firstly, we obtain the Company Mono from the CompanyService and then couple it with Employee Mono passed to the function. After this operation, our tuple instance is passed to the flatMap function allowing us to reference the Employee (t2) and Company (t1) instances.

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:

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

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

With that being done, let’s add the CompanyController class to our project:

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

    @PostMapping
    fun createCompany(@RequestBody request: CompanyRequest): Mono<CompanyResponse> {
        return companyService.createCompany(request)
            .map { CompanyResponse.fromEntity(it) }
    }

    @GetMapping
    fun findAllCompanies(): Flux<CompanyResponse> {
        return companyService.findAll()
            .map { CompanyResponse.fromEntity(it) }
            .delayElements(Duration.ofSeconds(2))
    }

    @GetMapping("/{id}")
    fun findCompanyById(@PathVariable id: String): Mono<CompanyResponse> {
        return companyService.findById(id)
            .map { CompanyResponse.fromEntity(it) }
    }

    @PutMapping("/{id}")
    fun updateCompany(
        @PathVariable id: String,
        @RequestBody request: CompanyRequest
    ): Mono<CompanyResponse> {
        return companyService.updateCompany(id, request)
            .map { CompanyResponse.fromEntity(it) }
    }

    @DeleteMapping("/{id}")
    fun deleteCompany(@PathVariable id: String): Mono<Void> {
        return companyService.deleteById(id)
    }
}

You might have noticed the usage of the delayElements function. It adds the pause between emitting each element from our Flux instance. I’ve added it to simulate the additional delay, which might happen in real-life scenarios (for instance, when processing the data, or calling other services).

Additionally, all functions return either the Flux or Mono instance, but why do we do that?

Well, with this approach, the behavior of the WebFlux will be dependent on the type of the incoming request:

• if we call the endpoint without specifying the Accept header, or when we set it to application/json, the request will be handled in a standard, blocking way returning a JSON in response
• however, if we set the Accept header value to the text/event-stream,  then the Server-Sent Event channel will be opened allowing the server to push the data to the client (in our case- with 2 seconds of the delay between each company response)

9.2. Create EmployeeController

Similarly, let’s implement the EmployeeController.

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

    @PostMapping
    fun createEmployee(@RequestBody request: EmployeeRequest): Mono<EmployeeResponse> {
        return employeeService.createEmployee(request)
            .map { EmployeeResponse.fromEntity(it) }
    }

    @GetMapping
    fun findAllEmployees(): Flux<EmployeeResponse> {
        return employeeService.findAll()
            .map { EmployeeResponse.fromEntity(it) }
    }

    @GetMapping("/{id}")
    fun findEmployeeById(@PathVariable id: ObjectId): Mono<EmployeeResponse> {
        return employeeService.findById(id)
            .map { EmployeeResponse.fromEntity(it) }
    }

    @GetMapping("/company/{companyId}")
    fun findAllByCompanyId(@PathVariable companyId: String): Flux<EmployeeResponse> {
        return employeeService.findAllByCompanyId(companyId)
            .map { EmployeeResponse.fromEntity(it) }
    }

    @PutMapping("/{id}")
    fun updateUpdateEmployee(
        @PathVariable id: ObjectId,
        @RequestBody request: EmployeeRequest
    ): Mono<EmployeeResponse> {
        return employeeService.updateEmployee(id, request)
            .map { EmployeeResponse.fromEntity(it) }
    }

    @DeleteMapping("/{id}")
    fun deleteEmployee(@PathVariable id: ObjectId): Mono<Void> {
        return employeeService.deleteById(id)
    }
}

10. Test with CURL

Finally, we can run our application 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"
}'

Nextly, let’s validate if the data has been added correctly in two ways. Let’s check out the blocking approach first:

curl 'localhost:8080/api/company'

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

As the next step, let’s test the endpoint utilizing the Server-Sent Event channel:

curl http://localhost:8080/api/company -H "Accept: text/event-stream"

# Example output
data:{"id":"5fcba07a30e3af4497f5de16","name":"Company 1","address":"Address 1"}

data:{"id":"5fcba07c30e3af4497f5de17","name":"Company 2","address":"Address 2"}

In the first case, we had to wait around 4 seconds for the server response (2 companies * 2 seconds of the delay). On the other hand, utilizing the SSE channel in the second case allows the server to push the data to the client chunk by chunk, with the delay between each entry.

Awesome, isn’t it? Let’s imagine that our endpoint returns thousands of data or the computation takes much longer. With the blocking request, we’d have to wait until everything will be processed to consume it. With the SSE, the client can process the data (for instance, displaying it immediately to the user) as soon, as it receives the first chunk.

After that, let’s validate if other endpoints are working as well. Let’s start by querying a specific company by the ID:

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.

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 deploying the MongoDB and a Docker container and creating the Reactive MongoDB REST API CRUD with Spring Boot and Kotlin.

Please don’t worry, if some of the topics covered in this article seem to be difficult or unclear. The WebFlux and reactive approach, in general, are really complex topics and they require some time and practice to fully understand them. If you would like to ask about anything or need some explanation, please do it in the comment section below, or by using the contact form.

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

Finally, if you found this article useful, then you may want to check out how to generate test reports with Jacoco.

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