Note: this article was created based on one of the services we implement in my Ktor Server Pro course. If you would like to learn how to expose a fully functional REST API, secure the application, and many many more, then don’t hesitate and secure your spot today😉

Before we start, I just wanted to mention that at the moment of writing KMongo is officially deprecated! Maybe you saw my previous article, maybe you saw some outdated content in some other places. Either way, we should not use that library anymore in favor of the official driver that comes in two flavors:

• MongoDB Kotlin Driver (for applications using coroutines)
• MongoDB Kotlin Sync Driver (for apps that require synchronous processing)

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Create & Verify MongoDB Instance

If you already have a MongoDB instance installed on your machine, feel free to skip this step.

On the other hand, if that is not the case, you can install it using the official manual. Or, if you just like me have a Docker environment, you can run the following command:

docker run --name my_awesome_mongo_name -d -p 27017:27017 mongo:8.0.4

This way, we run the Mongo docker container and expose it’s port 27017 .

And to verify it running, we can run the docker ps :

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                      NAMES
9ecd8986ac34   mongo:8.0.4   "docker-entrypoint.s…"   20 seconds ago   Up 19 seconds   0.0.0.0:27017->27017/tcp   my_awesome_mongo_name

As we can see, it was created successfully and we should be able to connect to it at localhost:27017

We can assert that, as well, for example with a free and official tool- MongoDB Compass:

And if we are able to connect, it means that we can head to the next step.

Create a New Ktor Project

Nextly, let’s navigate to the Ktor Project Generator page to create a fresh project from scratch.

If you use the IntelliJ Ultimate Edition, then you can generate it in your IDE

As we can see, we will be using Ktor 3.1.0 with Netty and configuration in the YAML file.

The important thing to mention here is that if we want to work with Kotlin coroutines, we should not select the below MongoDB plugin:

Because as we can see, this adds the MongoDB Kotlin Sync Driver for synchronous processing:

So, in our case, to keep our Ktor application as vanilla as possible, we will not add any additional plugins.

With that done, let’s hit the Download button and let’s import the project to our IDE.

Add MongoDB Async Driver to Ktor

Before adding the necessary import, let’s perform a small cleanup.

Firstly, let’s remove the Routing.kt file- we don’t need it for this tutorial.

Then, let’s navigate to the Application.kt and let’s get rid of routing config, as well. Eventually, we should have something like that:

 package com.codersee

import io.ktor.server.application.*

fun main(args: Array<String>) {
    io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {}

With that done, let’s add the MongoDB Kotlin Driver to work with coroutines.

During the configuration, we decided to use the Gradle version catalog. So now, we must navigate to the libs.versions.toml inside the gradle directory and add the mongodb-version along with mongodb-driver-kotlin:

[versions]
kotlin-version = "2.1.10"
ktor-version = "3.1.0"
logback-version = "1.4.14"
mongodb-version = "5.3.1"

[libraries]
ktor-server-core = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor-version" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor-version" }
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback-version" }
ktor-server-config-yaml = { module = "io.ktor:ktor-server-config-yaml", version.ref = "ktor-version" }
ktor-server-test-host = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor-version" }
kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin-version" }
mongodb-driver-kotlin = { module = "org.mongodb:mongodb-driver-kotlin-coroutine", version.ref = "mongodb-version" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-version" }
ktor = { id = "io.ktor.plugin", version.ref = "ktor-version" }

With that done, let’s navigate to build.gradle.kts and add the following line:

implementation(libs.mongodb.driver.kotlin)

Lastly, let’s sync the gradle project so that the necessary libraries are fetched.

Introduce Model Classes

Before we can start working with coroutines, we must prepare classes that will be translated into Mongo documents and vice versa.

To do so, let’s create the Product.kt class and put the following:

import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId

data class Product(
    @BsonId
    val id: ObjectId? = null,
    val name: String,
    val description: String,
    val price: Double,
    val category: ProductCategory,
    val tags: List<ProductTag>,
)

enum class ProductCategory {
    VIDEO_GAMES, TOOLS, HOME_AND_KITCHEN, FOOD
}

enum class ProductTag {
    EXCLUSIVE, HANDMADE, ORGANIC, BESTSELLER
}

As we can see, all fields except the id field are plain Kotlin classes. And later, they will be serialized/deserialized 1:1 when saving and retrieving from the database.

When it comes to the id field, we mark it using the @BsonId annotation. Thanks to that, it will be serialized to the _id BSON field that represents a primary key of our document. Moreover, we assign a default null value to it. This way, the value will be generated automatically.

Configure Ktor Connection to MongoDB

As the next step, let’s connect our Ktor application to the Mongo instance.

And for that purpose, let’s navigate to Application.kt and implement the following logic:

fun Application.module() {
    val settings = MongoClientSettings.builder()
        .applyConnectionString(
            ConnectionString("mongodb://localhost:27017")
        )
        .build()

    val client = MongoClient.create(settings)
    val database = client.getDatabase("application")
    val productCollection = database.getCollection<Product>("products")
}

Firstly, we instantiate the MongoClientSettings builder. A builder that allows us to configure the connection string for our database. Additionally, if you are looking for more configuration options, like reads or writes repetition, then you should start in there.

Then, we create a new client and pass our settings to it. If you would like to, then you could use another variant of the create function that takes the connection String as an argument:

public fun create(connectionString: String): MongoClient

But, in my opinion, using the builder approach is a better choice in terms of extensibility.

With that done, we get the instance of our database, by passing its name. Lastly, we obtain the MongoCollection that we will be injecting later into the product repository. Again, we pass the name of our collection, too.

To verify, let’s run our application.

As a result, we should see the following text in the logs indicating that everything is perfectly fine:

[cluster-ClusterId{value='67bd5f4689251d25d5077fb7', description='null'}-localhost:27017] INFO  org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=localhost:27017, type=STANDALONE, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=25, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=26289200, minRoundTripTimeNanos=0}

MongoDB Coroutines CRUD Operations

After we did all of that preparation, we can finally create the ProductRepository class:

class ProductRepository(
    private val productCollection: MongoCollection<Product>,
) { }

And inject the collection in Application.kt :

val productRepository = ProductRepository(productCollection)

The constructor injection is a great way to make our code easier to test in the future.

Anyway, coming back to the topic, let’s learn how we can how we can perform basic CRUD operations with coroutines.

Persits Products

Initially, our products collection is empty, so let’s add the following code to start populating it:

suspend fun save(product: Product): Product? {
    val result = productCollection.insertOne(product)

    return result.insertedId
        ?.let { product.copy(id = it.asObjectId().value) }
}

First of all, we must make our function suspend. Why? Because the insertOne we use is a suspend function, so we must invoke it either from the coroutine or another suspend function.

When it comes to the persisting- the function that we use returns the InsertOneResult that allows us to either get a boolean informing if the write was acknowledged or the generated identifier of the saved product. And in my opinion, reading that and returning a Product instance with the updated field is a quite nice approach.

After that, let’s get back to the Application.kt and test this function:

val saved = runBlocking {
    productRepository.save(
        Product(
            name = "Product 1",
            description = "Description 1",
            price = 19.99,
            category = ProductCategory.TOOLS,
            tags = listOf(ProductTag.EXCLUSIVE, ProductTag.BESTSELLER)
        )
    )
}

println(saved)

I know, the good, old println 🤠

Anyway, if we run our application, we should see the following in the logs:

Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

Additionally, when we hit the refresh button in MongoDB Compass, we should see the following:

And this proves that not only the Product was saved. But also, the application database and products collection was created by our client automatically.

Find By ID

Nextly, let’s implement the function to fetch product by identifier:

suspend fun findById(id: String): Product? {
    val objectId = ObjectId(id)

    return productCollection.find(
        eq("_id", objectId)
    ).firstOrNull()
}

This time, we use the find method. And this function returns the FindFlow which is the Flow implementation for find operations.

This function allows us to pass filters as arguments to it. And to get the particular product, we use the eq filter. One of the many filters that we can find in com.mongodb.client.model.Filters. We must remember that our identifier is of the ObjectId type, so we create a new instance from our String value.

Lastly, we invoke the firstOrNull– the terminal operator that returns the first element emitted by the flow and then cancels flow’s. We leverage the fact that only one element with such an identifier can be found in our database.

So with all of that done, let’s get back to the Application.kt and test this function:

val found = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874a")
}

val notFound = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874b")
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

// null

As we can see, our test proves that findById not only works but also it simply returns null when nothing was found. No unexpected exceptions, etc.

Updating Products

As the next step, let’s add the function responsible for updating products:

suspend fun update(id: String, product: Product): Product? {
    val objectId = ObjectId(id)

    return productCollection.findOneAndReplace(
        filter = eq("_id", objectId),
        replacement = product,
        options = FindOneAndReplaceOptions().returnDocument(ReturnDocument.AFTER)
    )
}

Again, this function is a suspended function, and again we use the same combination of the eq filter and ObjectId to find the item we are interested in.

The function that we use- findOneAndReplace– allows us to simply replace the existing document by passing a new version. Nevertheless, by default, this function returns the object before the update! And in my opinion, it makes more sense to return the updated versions in this case. And that’s why we specify the additional option.

As a note: if you would like to update just some fields, then the findOneAndUpdate may be a better choice.

With all of that done, let’s test our functionality:

val updated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874a",
        product = Product(
            name = "Updated Product 1",
            description = "Updated Description 1",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

val notUpdated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874b",
        product = Product(
            name = "Updated Product 2",
            description = "Updated Description 3",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Updated Product 1, description=Updated Description 1, price=20.11, category=FOOD, tags=[BESTSELLER])

// null

As we can see, everything works as expected. Our function returns the updated product. And moreover, it does not throw any exceptions when a product is not found!

Delete Products

Nextly, let’s take a look at how we can remove products from our database:

suspend fun deleteById(id: String): Boolean {
    val objectId = ObjectId(id)

    val deleteResult = productCollection.deleteOne(
        eq("_id", objectId)
    )

    return deleteResult.deletedCount == 1L
}

At this point of our MongoDB coroutines tutorial, I think the code is quite descriptive. We use the same pattern we did previously to find by ID and we utilize the function from DeleteResult to get the count of deleted items.

Of course, given we have only one item with a particular _id, the function returns true only if the count is equal to one.

And again, a small note from my end if you would like to return the deleted product instead, then you can use the findOneAndDelete instead.

I will skip the testing part here, you must trust me 😀

Case-insensitive Search In MongoDB

As the last step, I will show you how to utilize the function that we already know (find) to perform a case-insensitive search in MongoDB:

fun find(
    title: String,
): Flow<Product> {
    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
}

As we can see, this time we make use of the regex function, that will add the… regex filter 😀 And thanks to the “i” option, the whole search will be case-insensitive.

Additionally, we make use of the name field reference. We could use a simple String value- “name”- but thanks to our approach we won’t need to remember to manually update the name in case of the update.

Lastly, I just wanted to mention here that this is one of the approaches to tackle this issue. According to the Mongo docs, we have also two more options:

1. Create a case-insensitive index with a collation strength of 1 or 2, and specify that your query uses the same collation.
2. Set the default collation strength of your collection to 1 or 2 when you create it, and do not specify a different collation in your queries and indexes.

Adding Sorting and Pagination to Search Results

Lastly, let’s make a small adjustment to add pagination and sorting to our logic.

To do so, let’s implement the Order Enum first:

enum class Order {
    ASC, DESC
}

And with that done, let’s get back to our repository:

fun find(
    title: String,
    sortBy: String,
    order: Order,
    limit: Int,
    skip: Int,
): Flow<Product> {
    val sort = when (order) {
        Order.ASC -> ascending(sortBy)
        Order.DESC -> descending(sortBy)
    }

    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
        .sort(sort)
        .limit(limit)
        .skip(skip)
}

As we can see, our function allows us to pass 4 more arguments during the invocation: sortBy, order, limit, and skip.

So from now on, we can not only perform the search but also set the limit of results, ordering, as well as the order of items.

Summary

And that’s all for this tutorial on how to work with MongoDB and Kotlin coroutines in Ktor.

I hope you enjoyed it, and if you would like to learn more Ktor concepts in a fully hands-on manner, then check out my course.

Lastly, if you would like to get the whole codebase, then you can find it in this GitHub repository.

The post MongoDB with Kotlin Coroutines in Ktor appeared first on Codersee blog- Kotlin on the backend.

In some future articles, we will put that knowledge into action on the example of the Ktor project, emphasizing the Reactive approach. So don’t forget to follow me on LinkedIn to not miss out 🙂

Reactive Programming

If you try to search for what Reactive Programming is, you will sooner or later find The Reactive Manifesto, which is cited by almost everyone.

And in most articles, there will be something like the following diagram:

For the beginner, all of these definitions and explanations are vague and unclear. It is absolutely possible to learn it and speak about it, for example, in an interview with zero understanding whatsoever. Instead, let’s connect it to concepts that are present in software development, and don’t worry if you are not familiar with them.

Let’s take a look at another diagram that represents the concepts:

The key concepts in the Observer Pattern are “subjects” and “observers“. When a subject’s state changes, it notifies all its observers, allowing them to react accordingly.

The Iterator Pattern introduces a way to access elements of some object, most likely a collection, sequentially without exposing its internal implementation.

And as a cherry on top, Reactive Programming is tight with Functional Programming so, in essence, let’s define what Reactive Programming is in these terms. Reactive Programming leverages the Observer’s one-to-many notification and the Iterator’s sequential access, but extends them to handle continuous data flows and asynchronous interactions without defining “what” to do with data but “how” to iterate.

Streams

All mentioned before leads us to another core concept: Streams. If you are familiar with the Flows, it is basically them, if not we’ll cover them later anyway. So, a Stream is a sequence of data objects that can be consumed and processed asynchronously. What is more, you can also merge, filter, combine, and transform them to handle data successfully.

Now let’s check what Kotlin can offer in terms of the Reactive Approach. We will start with asynchronicity, and the best solution for this is Coroutines and especially Flows. But before that, let’s discuss types of streams.

“Cold” and “Hot” Streams

In terms of emitting data, we have two types of streams. On the one hand, “cold” streams are streams that can only emit data when there is someone who could consume it, in other words, if there is any observer attached. This basically means that no data would be missed and the whole chain of the items consumed.

On the other hand, we have “hot” streams. They are not dependent on any observable attached and start emitting items as soon as they are created. And here is the key difference, you could “miss” values using “hot” streams if they are not handled carefully.

Kotlin Coroutines

Quick dive into Coroutines basics, and then we will, Coroutines allow us to create an asynchronous code execution just like threads, but they are not bound to any particular thread and without callbacks.

Now for the real part, the Reactive Programming Coroutines library can offer 3 options:

• Channels
• StateFlow
• SharedFlow

Both StateFlow and SharedFlow are evolutions of the Flow which is generally a Stream I’ve mentioned before. Flow represents a sequence of values that can be computed asynchronously. But firstly, let’s start from Channels.

Channels

The first notable object is Chanel. As documentation states, Chanel provides communication between coroutines. But in terms of our topic, Chanel is a “hot” Stream in which each individual value could consume only one observer.

Nevertheless, it can have more the one observer, but the values would be delivered to the first awaited. If there are many observers that wait for the value to be delivered, some collectors will get suspended. Now let’s check a simple code example:

import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.delay
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

suspend fun fetchStockPrice(): Double {
    delay(1000) // Simulate API call delay
    return Math.random() * 100
}

fun main() = runBlocking {
    // Create a Chanel to hold stock prices
    val stockPrices = Channel<Double>()

    // Launch a coroutine to fetch prices every second
    launch {
        while (isActive) {
            val price = fetchStockPrice()
            stockPrices.send(price)
            delay(1000)
        }
    }

    // Launch a coroutine to consume and display prices
    launch {
        for (price in stockPrices) {
            println("Current Stock Price: $$price")
        }
    }

    delay(Long.MAX_VALUE)
}

This example simulates a stock price ticker application that fetches prices from an API in real time and displays them to the user.

We used Channel to handle the asynchronous data flow and transfer data from one Coroutine to another!

SharedFlow

The SharedFlow is a Stream in all of its glory.

It is a hot stream, that can have multiple numbers of observers. We can check it out with the following code example:

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.filter
import kotlinx.coroutines.flow.launchIn
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

data class Item(val name: String, val price: Double)

fun main() = runBlocking {
    // SharedFlow to hold the cart items
    val cartItems = MutableSharedFlow<List<Item>>()

    // Launch a coroutine to print the cart on SharedFlow
    launch {
        cartItems.collect { items ->
            println("Cart Updated: $items")
        }
    }

    // Launch another coroutine to trigger order confirmation when the cart is full
    launch {
        cartItems.filter { it.size >= 3 } // Filter for 3 or more items
            .onEach { println("Order Confirmation triggered!") }
            .launchIn(this)
    }

    // Launch a coroutine to simulate adding items to the cart
    launch {
        var updatedItems = listOf(Item("Apple", 1.50))
        cartItems.emit(updatedItems)
        delay(1000)
        updatedItems = updatedItems + Item("Milk", 2.00)
        cartItems.emit(updatedItems)
        delay(1000)
        updatedItems = updatedItems + Item("Bread", 3.00)
        cartItems.emit(updatedItems)
    }

    delay(Long.MAX_VALUE)
}

In the example above, we created a shopping cart application where multiple components need to react to changes in the cart items.

SharedFlow provides a centralized way to share updates efficiently. And we can witness multiple observers at the same time.

StateFlow

The StateFlow is similar to SharedFlow. However, it is a somewhat cold stream because it requires some initial value on creation, and it always holds a value.

This basically means that it always has a value to observe. Here’s a good example:

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

enum class PlayerState {
    Playing,
    Paused,
    Stopped
}

fun main() = runBlocking {
    // StateFlow to hold the current player state
    val playerState = MutableStateFlow(PlayerState.Stopped)

    // Launch a coroutine to print state based on StateFlow
    launch {
        playerState.collect { state ->
            println("Player State: $state")
        }
    }

    // Launch a coroutine to simulate user actions
    launch {
        // Play/pause/stop actions update the state
        playerState.emit(PlayerState.Playing)
        delay(2000)
        playerState.emit(PlayerState.Paused)
        delay(1000)
        playerState.emit(PlayerState.Stopped)
    }

    delay(Long.MAX_VALUE)
}

For this example, we use a music player application where the current playing state needs to be tracked. StateFlow provides a single source of truth for this state, with an initial value.

Other Reactive options available

The most popular alternatives are ReactiveX libraries. The main competitor is RxJava for Java basically and it’s widely used especially in Android Development. Unfortunately, RxKotlin has almost zero popularity these days due to its extensive RxJava presence.

RxJava provides extensive tools for Reactive programming, but due to its limited integration with Kotlin Coroutines, I recommend using Coroutines but keep in mind that this powerful tool is also available.

There are also lots of libraries tightly connected to Spring Boot. There are Spring WebFlux, and Project Reactor. They are provided tools in applications for building reactive systems in JVM Backend Development, but not that popular in Kotlin.

Summary

And that’s all for this article about Reactive Programming in Kotlin with Coroutines and Flows.

In the upcoming articles, we will get back to this topic and learn how to apply this knowledge with Ktor, so don’t forget to join the free newsletter to not miss it!

Lastly, if you would like to learn more about Flows, then you can find lots of useful information on the official documentation of Kotlin.

The post Reactive Programming in Kotlin: A Step-by-Step Guide appeared first on Codersee blog- Kotlin on the backend.

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.