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.

Ktor is a flexible library that provides the ability to create a non-blocking HTTP client, which enables you to perform requests and handle responses. Its functionality could be enhanced with plugins, such as logging, serialization, authentication, and so on. Its core benefit is that it’s a lightweight framework that can be used on different platforms such as Android, JVM, or Native!

General Overview

Let’s discuss some basic information for everyone to be on the same page.

Today, we are going to write HTTP requests and receive responses. There are different types of requests but OpenWeatherMap for the most part utilizes GET requests with various parameters.

OpenWeatherMap API, as you can tell by its name, is an API for retrieving weather-related data. It provides various types of data but we’re going to use only 3 of them:

• Current Weather,
• 3-hours Forecast,
• and Air Pollution API.

To start using OpenWeatherMap you need to register and get your special API key. It has lots of free options and for our sake, we don’t need to pay at all.

But be aware of the limitations of the call: 1,000 API calls per day for free!

Gradle Dependencies

For this project, we’re going to use basic Ktor’s client, serialization, engines, and logging.

Your build.gradle.kts file would look like this:

val ktor_version: String by project
val kotlin_version: String by project
val logback_version: String by project

plugins {
    kotlin("jvm") version "1.9.21"
    id("io.ktor.plugin") version "2.3.6"
    id("org.jetbrains.kotlin.plugin.serialization") version "1.9.21"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.ktor:ktor-client-core-jvm")
    implementation("io.ktor:ktor-client-cio-jvm")

    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm")
    implementation("io.ktor:ktor-client-content-negotiation-jvm")

    implementation("ch.qos.logback:logback-classic:$logback_version")
    implementation("io.ktor:ktor-client-logging:$ktor_version")
    implementation("io.ktor:ktor-client-apache5:$ktor_version")

    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
}

Creating Models

The first step of creating a Ktor client is actually revealing what we’re gonna handle. Basically, we need 2 types of models: request and response. All necessary information is located on the corresponding page of the documentation. The documentation is pretty neat and, generally, it’s a good practice to check it out during the coding!

To optimize the process we could spot similar parameters appearing in the Current Weather and Weather Forecast. Such as Mode and Units.

So we can create separate classes and use the latter like this:

enum class ResponseUnits {
    STANDARD,
    METRIC,
    IMPERIAL
}

enum class ResponseMode {
    XML
}

Now let’s create the request themselves.

As there are some optional parameters present we’re going to make them nullable with default value null so that we could use them or not with ease.

Here are the models for requests:

data class CurrentWeatherRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null
)

data class WeatherForecastRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null,
    val count: Int? = null
)

data class AirPollutionRequest(
    val latitude: Double,
    val longitude: Double
)

Consequently, we desperately need models to put our data to: the response models.

It’s the most routine process because there are some huge responses and by ‘huge’ I mean lots of parameters. Let’s dive deep into one model and the rest would be easy to create.

Here’s what our JSON of current weather data looks like (there is also a text representation of this JSON with more information about parameters):

{
  "coord": {
    "lon": 10.99,
    "lat": 44.34
  },
  "weather": [
    {
      "id": 501,
      "main": "Rain",
      "description": "moderate rain",
      "icon": "10d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 298.48,
    "feels_like": 298.74,
    "temp_min": 297.56,
    "temp_max": 300.05,
    "pressure": 1015,
    "humidity": 64,
    "sea_level": 1015,
    "grnd_level": 933
  },
  "visibility": 10000,
  "wind": {
    "speed": 0.62,
    "deg": 349,
    "gust": 1.18
  },
  "rain": {
    "1h": 3.16
  },
  "clouds": {
    "all": 100
  },
  "dt": 1661870592,
  "sys": {
    "type": 2,
    "id": 2075663,
    "country": "IT",
    "sunrise": 1661834187,
    "sunset": 1661882248
  },
  "timezone": 7200,
  "id": 3163858,
  "name": "Zocca",
  "cod": 200
}

Now we have to face some difficulties. Not only do we have to parse it but also there are some optional parameters.

To solve the first issue we mark our classes with @Serializable and @SerialName annotations. I highly recommend using @SerialName because it provides enhanced readability and usability especially when handling such long classes.

To solve the second problem I recommend you to read my detailed guide that covers all essential information about Serialization. Basically, if we want to parse all of the data, we make optional fields with @EncodeDefault and make it nullable with the default value as null. This makes sure that if there was no such a field we would get a null, without any exceptions.

Now let’s look at classes for our Ktor client:

@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class CurrentWeather(
    @SerialName("coord") val coordinates: Coordinates,
    @SerialName("weather") val weather: List<Weather>,
    @SerialName("base") val base: String,
    @SerialName("main") val main: Main,
    @SerialName("visibility") val visibility: Int,
    @SerialName("wind") val wind: Wind,
    @SerialName("rain")
    @EncodeDefault
    val rain: Rain? = null,
    @SerialName("snow")
    @EncodeDefault
    val snow: Snow? = null,
    @SerialName("clouds") val clouds: Clouds,
    @SerialName("dt") val dateTime: Long,
    @SerialName("sys") val systemData: SystemData,
    @SerialName("timezone") val timezone: Int,
    @SerialName("id") val cityId: Int,
    @SerialName("name") val cityName: String,
    @SerialName("cod") val code: Int
) {

    //other classes here

    @Serializable
    data class Wind(
        @SerialName("speed") val speed: Double,
        @SerialName("deg") val direction: Int,
        @SerialName("gust") val gust: Double
    )

    @Serializable
    data class Rain(
        @SerialName("1h")
        @EncodeDefault
        val oneHour: Double? = null,
        @SerialName("3h")
        @EncodeDefault
        val threeHours: Double? = null
    )

	//other classes here
}

The rest of the responses are quite similar so you could check them out in the repository that comes with this article.

Quick remark, I’ve made classes such as Coordinates, Weather, etc. as inner classes since there are the same classes for other responses but with different structures.

This approach helps not to mix them up.

Creating The Ktor Client Itself

We are gonna be using Ktor’s HttpClient with some adjustments and extended configuration.

Let’s check it out:

private val client = HttpClient(Apache5) {
        install(ContentNegotiation) {
            json(Json {
                isLenient = false
            })
        }
        install(Logging)
        defaultRequest {
            url {
                protocol = URLProtocol.HTTPS
                host = "api.openweathermap.org/data/2.5"
            }
        }
    }

First of all, we have the Apache5 engine rather than CIO, for example, because it’s suitable for HTTP/2 while CIO is not.

Next, we have 2 plugins: the ContentNegotiation for the JSON parsing and the Logging for detailed logs.

Also, as all of our requests to OpenWeatherMap have similar endpoints, we can use defaultRequest to shorten our request’s links. The whole defaultRequest translates to https://api.openweathermap.org/data/2.5/. We’ll combine this with the request’s specific parameters.

Now let’s talk about them.

Creating Routes

As all of our routes would share similar logic let’s look closely at only one of them for the Current Weather:

suspend fun getCurrentWeather(currentWeatherRequest: CurrentWeatherRequest): CurrentWeather? {
        return try {
            val response: HttpResponse = client
                .get("/weather") {
                    url {
                        parameters.append("lat", currentWeatherRequest.latitude.toString())
                        parameters.append("lon", currentWeatherRequest.longitude.toString())
                        parameters.append("appid", APP_ID)
                        if (currentWeatherRequest.mode != null) parameters.append(
                            "mode",
                            currentWeatherRequest.mode.name()
                        )
                        if (currentWeatherRequest.units != null) parameters.append(
                            "units",
                            currentWeatherRequest.units.name()
                        )
                        if (currentWeatherRequest.language != null) parameters.append(
                            "lang",
                            currentWeatherRequest.language
                        )
                    }
                }

            if (response.status == HttpStatusCode.OK) {
                response.body<CurrentWeather>()
            } else {
                println("Failed to retrieve current weather. Status: ${response.status}")
                null
            }
        } catch (e: Exception) {
            println("Error retrieving current weather: ${e.message}")
            null
        }
    }

Here we create GET HttpResponse with the path “/weather” and then we specify additional parameters, note that it’ll automatically use the correct notation(? and other).

In the URL block, we list all of our parameters using parameters.append() function that takes the name and the value. There is no need to include optional parameters that are not specified, so we simply check whether they’re null or not.

Our Ktor client also implements error handling.

For the errors with the request itself, such as connection problems, any issues from the server, etc. we’ll get the “Error retrieving current weather:” message and null result.

And if your request is successful but has some undesired response, in our case everything except 200 OK, we’ll get “Failed to retrieve current weather. Status:” and null result as well.

Ktor Client In Action

To use the client you could simply call our object with the corresponding method like this:

WeatherClient.getCurrentWeather(
        CurrentWeatherRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getWeatherForecast(
        WeatherForecastRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getAirPollution(
        AirPollutionRequest(
            latitude = 50.0,
            longitude = 50.0
        )
    )

This could be used on every platform but as I’ve mentioned before make sure you’re using the correct engine!

Summary

And that’s all for this article about the OpenWeatherMap API Ktor client.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Create a Ktor Client To Connect To OpenWeatherMap API appeared first on Codersee blog- Kotlin on the backend.

• Ktor Server
• Ktor Client
• WebSockets in Ktor

Before we start, I just wanted to note that we are going to use a modified project from the lesson about Ktor with Ktorm and PostgreSQL. So if you don’t know how to set up and use a Ktor server with PostgreSQL you should definitely check it up, because I will skip the basics. Additionally, if you’d like to explore kotlinx.serialization in details, then check out my detailed guide.

Lastly, please note that there is a GitHub repository for all of this in the end of this lesson!

Setup

A few quick words about setting up. Note that for the main thing we are going to use, such as ContentNegotiation, Ktor has different implementations for Client and Server.

Do not mess them up, it causes a lot of trouble and a lot of Stack Overflow questions 🙂

//server
implementation("io.ktor:ktor-server-content-negotiation-jvm")
//client
implementation("io.ktor:ktor-client-content-negotiation-jvm")

kotlinx.serialization With Ktor Server

Now, let’s start with the kotlinx.serialization for the Ktor server part.

I am going to use Postman for making HTTP requests and testing the server. You can use any tool for this purpose even the client we will write about in the next part 🙂

First of all, let’s check our classes for the User from previous parts:

interface User : Entity<User> {  
  companion object : Entity.Factory<User>()  
  
  val userId: Long?  
  var userName: String  
}

 Now we are going to need classes for our responses: 

@Serializable  
data class UserResponse(  
  val userId: Long,  
  val userName: String  
)  
  
@Serializable  
data class UserRequest(  
  val userName: String  
)

@Serializable  
data class UserErrorResponse(val message: String)

Basically, the central part of all serialization here is ContentNegotiation which could be installed for our server(not the client).

As we are using it for Json serialization, we should specify it as json() like this:

fun Application.configureSerialization() {  
  install(ContentNegotiation) {  
    json(Json {  
      prettyPrint = true  
      isLenient = true  
    })  
  }  
}

And here’s our loved Json object! Now we can do all kinds of trickery that we know and learned before.

For the code above, I’ve used a simple style specification, but you can use it as you like. As an example, we can add a custom or polymorphic serializer:

private val contextualSerializerModule = SerializersModule {
  contextual<Date>(DateAsStringSerializer)
}

private val polymorphicSerializationModule = SerializersModule {
  polymorphic(User::class) {
    subclass(Admin::class, Admin.serializer())
    subclass(Guest::class, Guest.serializer())
  }
}

object DateAsStringSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor(
    "Date", 
    PrimitiveKind.STRING,
  )

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

And our server is going to look like this: 

fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
      serializersModule = contextualSerializerModule
      serializersModule = polymorphicSerializationModule
    })
  }
}

We can remove this for now, we’ll use actual polymorphic serialization in the Web Sockets section.

Now, what about routes? Let’s check out a simple POST request:

fun Route.createUser(userService: UserService) {
  post {

    val request = call.receive<UserRequest>()

    val success = userService.createUser(userRequest = request)

    if (success)
      call.respond(HttpStatusCode.Created)
    else
      call.respond(HttpStatusCode.BadRequest, UserErrorResponse("Cannot create user"))
  }
}

As we can see, we don’t serialize/deserialize anything manually.

The whole process happens due to this line:

val request = call.receive<UserRequest>()

We can witness that our request deserializes into the UserRequest as such is marked with @Serializable annotation.

The same happens here:

fun Route.updateUserByIdRoute(userService: UserService) {
  patch("/{userId}") {
    val userId: Long = call.parameters["userId"]?.toLongOrNull()
      ?: return@patch call.respond(
          HttpStatusCode.BadRequest, 
          UserErrorResponse("Invalid id")
        )

    val request = call.receive<UserRequest>()
    val success = userService.updateUserById(userId, request)

    if (success)
      call.respond(HttpStatusCode.NoContent)
    else
      call.respond(
        HttpStatusCode.BadRequest,
        UserErrorResponse("Cannot update user with id [$userId]"),
      )
  }
}

Our request is deserialized and we can update a user.

Now let’s test it and get our users:

private fun User?.toUserResponse(): UserResponse? =  
    this?.let { UserResponse(it.userId!!, it.userName) }

fun Route.getAllUsersRoute(userService: UserService) {  
    get {  
        val users = userService.findAllUsers()  
            .map(User::toUserResponse)  
  
        call.respond(message = users)  
    }  
}

As I said before, I’m going to use Postman.

So how about checking our server:

Post:

Delete:

kotlinx.serialization With Ktor Client

Now the kotlinx.serialization for the Ktor client. Here’s the same thing, but make sure you don’t miss anything and use ContentNegotiation FOR CLIENT.

Check the import:

import io.ktor.client.plugins.contentnegotiation.*

We can install it just like before:

private val client = HttpClient(CIO) {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
    })
  }
  defaultRequest {
    url {
      host = "0.0.0.0"
      path("/")
      port = 8080
    }
  }}

All things apply here as well, so let’s check how to use it for our requests. There are lots of possible situations, we are going to cover basic data retrieving and how to place something inside a body of a request.

We want to get all of the users, what should we do? We can use something like this:

suspend fun getAllUsers(): List<UserResponse> {
  return try {
    val response: HttpResponse = client.get("/users")

    if (response.status == HttpStatusCode.OK) {
      response.body<List<UserResponse>>()
    } else {
      println("Failed to retrieve users. Status: ${response.status}")
      emptyList()
    }
  } catch (e: Exception) {
    println("Error retrieving users: ${e.message}")
    emptyList()
  }
}

The main part here as well is this:

response.body<List<UserResponse>>()

The UserResponse class can be serialized, and we don’t need to do anything at all. All hail the ContentNegotiation 🙂

How about we create some user? We can do it as well:

suspend fun createUser(user: UserRequest) {
  try {
    val response: HttpResponse = client.post("/users") {
      contentType(ContentType.Application.Json)
      setBody(user)
    }

    if (response.status == HttpStatusCode.Created) {
      println("User created successfully")
    } else {
      println("Failed to create user. Status: ${response.status}")
    }
  } catch (e: Exception) {
    println("Error creating user: ${e.message}")
  }
}

This time, we specify the content type for our body, such as ContentType.Application.Json and just set our user in here. All happens as it is a miracle.

Now let’s test it. I’m going to use this simply to check each method:

runBlocking {

  val allUsersOld = UserRequests.getAllUsers()
  println("All Users: $allUsersOld")

  val newUser = UserRequest(
    userName = "Mark"
  )

  UserRequests.createUser(newUser)

  val allUsersNew = UserRequests.getAllUsers()
  println("All Users: $allUsersNew")

  val userIdToRetrieve = 2L
  val retrievedUser = UserRequests.getUserById(userIdToRetrieve)
  println("User with ID $userIdToRetrieve: $retrievedUser")

  val userIdToUpdate = 2L
  val updatedUser = UserRequest(
    userName = "Bob"
  )
  UserRequests.updateUserById(userIdToUpdate, updatedUser)

  val userIdToDelete = 2L
  UserRequests.deleteUserById(userIdToDelete)
}

And the corresponding result would be something like this:

...
All Users: [UserResponse(userId=2, userName=User #2)]
...
User created successfully
...
All Users: [UserResponse(userId=2, userName=User #2), UserResponse(userId=7, userName=Mark)]
...
User with ID 2: UserResponse(userId=2, userName=User #2)
...
User updated successfully
...
User deleted successfully

I’ve skipped the logs because they are not important for this. 

Web Sockets

So, here’s the fun part. There is no Content Negotiation for the Web Sockets 🙁

Nonetheless, there is such thing as contentConverter for WebSockets:

private val client = HttpClient(CIO).config {
  install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(
      Json
    )
  }
}

Basically, that’s it, now we can use sendSerialized() and receiveDeserialized() to send and receive data.

However, let’s focus more on manual implementation for the sake of understanding. Here we have classes to represent our messages:

@Serializable
abstract class Message {
  abstract val content: String
}

@Serializable
@SerialName("text")
class TextMessage(override val content: String) : Message()

@Serializable
@SerialName("system")
class SystemMessage(override val content: String, val systemInfo: String) : Message()

private val module = SerializersModule {
  polymorphic(Message::class) {
    subclass(TextMessage::class, TextMessage.serializer())
    subclass(SystemMessage::class, SystemMessage.serializer())
  }
}

val messagesFormat = Json {
  serializersModule = module
}

We are going to use TextMessage to send to the server and SystemMessage to send back from the server.

To send a message we must serialize it to string. And to receive vice versa. Nothing difficult: 

@OptIn(ExperimentalSerializationApi::class)
private suspend fun DefaultClientWebSocketSession.receiveMessage() {
  try {
    for (message in incoming) {
      message as? Frame.Text ?: continue
      val deserializedMessage: Message =
        messagesFormat.decodeFromStream(message.data.inputStream())
      println("${deserializedMessage.content} // ${(deserializedMessage as? SystemMessage)?.systemInfo}")
    }
  } catch (e: Exception) {
    println("Error while receiving: " + e.localizedMessage)
  }
}

private suspend fun DefaultClientWebSocketSession.sendMessage(message: Message) {
  val serializedMessage = messagesFormat.encodeToString(message)
  try {
    send(serializedMessage)
  } catch (e: Exception) {
    println("Some error occur: " + e.localizedMessage)
    return
  }
}

Here’s our simple server that going to get our message and send it back with some changes:

routing {
  webSocket("/hello") {
    try {
      for (frame in incoming) {
        frame as? Frame.Text ?: continue
        val deserializedMessage: WebSocketSession.Message =
          WebSocketSession.messagesFormat.decodeFromStream(frame.data.inputStream())
        val newMessageText = deserializedMessage.content + " - from Client"
        val serializedMessage = WebSocketSession.messagesFormat.encodeToString<WebSocketSession.Message>(
          WebSocketSession.SystemMessage(
            content = newMessageText,
            systemInfo = "Important"
          )
        )
        Connection(this).session.send(serializedMessage)
      }
    } catch (e: Exception) {
      println(e.localizedMessage)
    }
  }
}

The final part is to test it. We simply connect it to our already existing server:

fun main() {
  embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
    configureUserRoutes()
    configureSerialization()
    configureSockets()
  }.start(wait = true)
}

And now run the client, for example, I’ve created this one:

suspend fun connectWebSocket() {
  client.webSocket(
    host = "0.0.0.0",
    port = 8080,
    path = "/hello"
  ) {
    launch { sendMessage(TextMessage("Good morning!")) }
    launch { receiveMessage() }
    delay(2000)
    launch { sendMessage(TextMessage("Hello!")) }
    launch { receiveMessage() }
    delay(2000)
    println("Connection closed. Goodbye!")
    client.close()
  }
}

runBlocking {
  WebSocketSession.connectWebSocket()
}

Here’s the results:

2023-12-01 15:46:26.104 [DefaultDispatcher-worker-4] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 41) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:26.110 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 82)
Good morning! - from Client // Important
2023-12-01 15:46:28.094 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 34) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:28.097 [DefaultDispatcher-worker-3] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 75)
Hello! - from Client // Important
Connection closed. Goodbye!

Summary

And that’s all for this article about kotlinx.serialization with Ktor.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Use kotlinx.serialization with Ktor and Kotlin? appeared first on Codersee blog- Kotlin on the backend.

If you haven’t heard about it, then Kotlin Serialization is a cross-platform and multi-format framework built for this specific needs. It can be used with practically any Kotlin-based project, such as Android applications, Ktor applications, and Multiplatform (Common, JS, Native). 

Setting Up

To set up kotlinx.serialization in our project, we must add the following lines in your build.gradle.kts.

plugins {

    kotlin("jvm") version "1.9.20" // or kotlin("multiplatform")

    kotlin("plugin.serialization") version "1.9.20"

}

This will add the plugin.

Following, let’s add the implementation of the library itself:

repositories {

    mavenCentral()

}

dependencies {

    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.1")

}

Now we’re ready to go!

Basic Serialization

Simple Objects

You may not used this library yourself but you might have seen a @Serializable annotation before.

This is practically all we’re going to need to set up a serialization for a particular class, like this: 

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

Now, to manually serialize it, we only need to use a Json.encodeToString().

For example:

val data = User(userId = 1, userName = "Alice")
println(
  Json.encodeToString(data)
)

The output would be the following:

{"userId":1,"userName":"Alice"}

On the other hand, to deserialize something, we’ll use Json.decodeFromString():

val data = """  
  {
    "userId": 1,
    "userName":"Alice"
  }
"""  

println(
  Json.decodeFromString(
    User.serializer(), 
    data
  )
)

The output:

User(userId=1, userName=Alice)

kotlinx.serialization has also some useful functions to work with InputStream rather than with String. However, they are experimental at the moment and require using @OptIn(ExperimentalSerializationApi::class).

What am I talking about here? The Json.encodeFromStream() and Json.decodeFromStream(), which come in handy when we are dealing with Files.

Let’s take a look at how we can get data from the file without reading it and converting it to String. It saves lots of computation time, particularly on a big scale:

@OptIn(ExperimentalSerializationApi::class)
fun deserializeFile(file: File): User {
  return Json.decodeFromStream(
    User.serializer(),
    file.inputStream()
  )
}

Similarly, to encode it to a file we will use the encodeToStream: 

@OptIn(ExperimentalSerializationApi::class)
fun serializeFile(user: User, file: File) {
  Json.encodeToStream(
    User.serializer(),
    user,
    file.outputStream()
  )
}

Nested(Referenced) Objects

As the next step, let’s talk about nested serialization.

Highly likely, that some of your classes have a property that is another class.

In such a case, there is practically no difference from the previous section, just all of our classes have to have a @Serializable annotation:

@Serializable
data class Profile(
  val id: Int,
  val user: User
)

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

Let’s check it out like this:

val originalProfile = Profile(
  id = 123, 
  user = User(userId = 1, userName = "Alice")
)
  
println( 
  Json.encodeToString(
    Profile.serializer(), 
    originalProfile
  )
)  

val jsonString = """  
  {
    "id":123,
    "user": {
      "userId": 1,
      "userName":"Alice"
    }
  }
"""  

val deserializedProfile = Json.decodeFromString(
  Profile.serializer(), 
  jsonString
)
  
println(deserializedProfile)

The output:

{"id":123,"user":{"userId":1,"userName":"Alice"}}
Profile(id=123, user=User(userId=1, userName=Alice))

Lists

To serialize the whole List, we can use the ListSerializer constructor to create a serializer for any type of list, as long as we provide a serializer for the element type.

For example:

val originalUsers = listOf(
  User(userId = 1, userName = "Alice"),
  User(userId = 2, userName = "Bob")
)  

println(
  Json.encodeToString(
    ListSerializer(User.serializer()), 
    originalUsers
  )
)  

val jsonString = """ 
  [
    {"userId":1,"userName":"Alice"},
    {"userId":2,"userName":"Bob"}
  ] 
"""  

val deserializedUsers = Json.decodeFromString(
  ListSerializer(User.serializer()), 
  jsonString
)  

println(deserializedUsers)

That code will give us:

[{"userId":1,"userName":"Alice"},{"userId":2,"userName":"Bob"}]
[User(userId=1, userName=Alice), User(userId=2, userName=Bob)]

Generics

Basically, generics serialization works the same as nested objects.

The kotlinx.serialization has type-polymorphic behavior, which means that JSON relies on the actual type parameter. It will be compiled successfully if the actual generic type is a serializable class.

To check that, let’s modify our classes:

@Serializable
data class Profile<T>(
  val id: T,
  val user: Wrapper<T>
)

@Serializable
data class Wrapper<T>(val contents: T)

Now we can check how it will work with different T for user fields:

val profile1 = Profile(
  1, 
  Wrapper(
    User(userId = 1, userName = "Alice")
  )
)  
val profile2 = Profile(
  2, 
  Wrapper(42)
)  
  
val jsonProfile1 = Json.encodeToString(profile1)  
val jsonProfile2 = Json.encodeToString(profile2)  
  
println(jsonProfile1)  
println(jsonProfile2)  
  
val jsonString1 = """ 
  {
    "id": 1,
    "user": {
      "contents": {
        "userId": 1,
        "userName": "Alice"
      }
    }
  } 
"""  
val jsonString2 = """ 
  {
    "id": 2,
    "user": {
      "contents": 42
    }
  } 
"""  
  
val deserializedProfile1 = Json.decodeFromString(
  Profile.serializer(
    User.serializer()
  ),
  jsonString1
)  
val deserializedProfile2 = Json.decodeFromString(
  Profile.serializer(
    Int.serializer()
  ), 
  jsonString2
)  
  
println(deserializedProfile1)  
println(deserializedProfile2)

There will be the following output: 

{"id":1,"user":{"contents":{"userId":1,"userName":"Alice"}}}
{"id":2,"user":{"contents":42}}
Profile(id=1, user=Wrapper(contents=User(userId=1, userName=Alice)))
Profile(id=2, user=Wrapper(contents=42))

Customizing serialization and deserialization

In this paragraph, we are gonna talk about making your objects a little bit appealing with variable behavior to adjust our specific needs.

Custom names

As you have noticed, the basic name of a field is taken by default.

To create a custom name, the only thing we need is a @SerialName annotation:

@Serializable
data class User(
  @SerialName("id") val userId: Int,
  @SerialName("login") val userName: String
)

Now let’s use it as we used in the example at the beginning:

val data = User(userId = 1, userName = "Alice")
println(
  Json.encodeToString(data)
)

We’ll get:

{"id":1,"login":"Alice"}

But we must be careful- this works both ways.

After the change, we must make sure that the incoming JSON contains the names that we mentioned in the @SerialName:

val data = """{"id":1,"login":"Alice"}"""         //correct
val data = """{"userId":1,"userName":"Alice"}"""  //wrong

Default values

Now things get a little bit trickier. Default values are not encoded by default.

So, if we want them to, we need the @EncodeDefault annotation:

@Serializable
data class User(
  val userId: Int,
  @EncodeDefault val userName: String = "user"
)

This way, we could omit a userName and the serialization library will use the default value:

val data = User(userId = 1)
println(
  Json.encodeToString(data)
)

Let’s see:

{"userId":1,"userName":"user"}

Excellent, works as expected!

But here is a different situation. What if we want to deserialize a JSON with some optional fields?

For it to compile properly, we must provide a default value for these fields:

@Serializable
data class User(
  val userId: Int,
  val userName: String = "user"
)

Now we can deserialize an object like this: 

val data = """
  {
    "userId": 1
  }
"""
  
println(
  Json.decodeFromString(
    User.serializer(),
    data
  )
)

Output: 

User(userId=1, userName=user)

On the other hand, if we want an optional field to be present in JSON, we may use a @Required annotation:

@Serializable
data class User(
  val userId: Int,
  @Required val userName: String = "user"
)

If we use this class with the code before, we will get an error, which can be useful in some scenarios:

Exception in thread “main” kotlinx.serialization.MissingFieldException: Field ‘userName’ is required for type with serial name ‘com.example.User’, but it was missing

Nulls

Kotlin’s language is known for its type safety. The kotlinx.serialization knows it as well.

We cannot decode a null value into a non-nullable property or we get an exception. For example, for this class:

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

We cannot expect to serialize this object below:

val data = """
  {
    "userId": 1,
     "userName": null
  }
"""
  
println(
  Json.decodeFromString(
    User.serializer(),
    data
  )
)

It will result in an error.

To avoid it, we should do this instead:

@Serializable
data class User(
  val userId: Int,
  val userName: String?
)

This time, our result will be: 

User(userId=1, userName=null)

As we can see, default values are not encoded by default.

So to get a missing property from JSON not as an optional but as a null value, we have to use @EncodeDefault:

@Serializable
data class User(
  val userId: Int,
  @EncodeDefault val userName: String? = null
)

That is what we’ll see for our class:

{"userId":1,"userName":null}

However, if we forget the annotation, this is what we will get:

{"userId":1}

Advanced Serialization

This section is probably what you are looking for if you have a complex project.

These are the most sophisticated tricks of kotlinx.serialization, but the most useful, though. And now we are going to understand how they work.

From now on everything becomes more complex. So we have to establish ground rules and basic terms.

What Exactly Is a Polymorphism?

Polymorphism in Kotlin is the ability of an object or a function to have different forms or behaviors depending on the context. A polymorphic object can belong to different classes and respond to the same method call in different ways.

There are two types of polymorphism in Kotlin: compile-time and run-time:

• Compile-time polymorphism, also known as static polymorphism, is achieved through function overloading. It allows the name of functions, i.e., the signature, to be the same but return type or parameter lists to be different.
• Run-time polymorphism, or dynamic polymorphism, is achieved through function overriding and inheritance. In the run-time polymorphism, the compiler resolves a call to overload methods at the runtime.

But there is more. For serialization, we are going to talk about different approaches. To serialize an object, we should know what that object is in the first place and can its behavior can be changed. So there are 2 more types of polymorphism:

• Closed polymorphism means that the behavior of an object is fixed and cannot be changed by subclasses or external factors.
• Open polymorphism means that the behavior of an object can be modified or extended by subclasses or external factors.
  This is how the library sees polymorphism for the most part.

The Practice Part

First things first, let’s talk about closed polymorphism in kotlinx.serialization.

The first and the most obvious thing to do is to make all of our classes serializable:

@Serializable
open class User(
  val userId: Int,
  val userName: String?
)

@Serializable
@SerialName("admin")
class Admin(
  val adminId: Int,
  val adminName: String?,
  val adminRole: String
) : User(adminId, adminName)

Let’s check it out: 

fun serializeAdmin() {
  val admin: User = Admin(
    adminId = 1,
    adminName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

Everything works as expected, our Admin is indeed a user: 

{"userId":1,"userName":"Alice"}

But what will happen if we try to serialize an Admin object:

fun serializeAdmin() {
  val admin = Admin(
    adminId = 1,
    adminName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

Let’s find out:

{"userId":1,"userName":"Alice","adminId":1,"adminName":"Alice","adminRole":"Boss"}

So you have to keep that in mind. This may be a bit odd.
Following this, I want to cover sealed classes as well. Not because I’m a huge fan of it, which I am, but because of its natural behavior (we know all of its children at the runtime) that helps our process:

@Serializable
sealed class User {
  abstract val userId: Int
  abstract val userName: String?
}

@Serializable
@SerialName("admin")
class Admin(
  override val userId: Int,
  override val userName: String?,
  val adminRole: String
) : User()

We are going to check our first scenario: 

fun serializeAdmin() {
  val admin: User = Admin(
    userId = 1,
    userName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

As expected, now we know the type of our user beforehand: 

{"type":"admin","userId":1,"userName":"Alice","adminRole":"Boss"}

For a closed polymorphism, things get different. Now we have to create a SerializersModule and provide explicit subclasses that are to be serialized.

Let’s create an additional class to show this in action:

@Serializable
abstract class User {
  abstract val userId: Int
  abstract val userName: String?
}

@Serializable
@SerialName("admin")
class Admin(
  override val userId: Int,
  override val userName: String?,
  val adminRole: String
) : User()

@Serializable
@SerialName("guest")
class Guest(
  override val userId: Int,
  override val userName: String?,
  val guestEmail: String?
) : User()

Now comes the module:

val module = SerializersModule {
  polymorphic(User::class) {
    subclass(Admin::class, Admin.serializer())
    subclass(Guest::class, Guest.serializer())
  }
}

We’ve used a Json instance for our needs before. Now we have to create a specific instance with our module:

val format = Json { serializersModule = module }

With that done, let’s check it:

fun serializeAdmin() {
  val admin: User = Admin(
    userId = 1,
    userName = "Alice",
    adminRole = "Boss"
  )
  val guest: User = Guest(
    userId = 1,
    userName = "Alice",
    guestEmail = "guest@email.com"
  )

  println(format.encodeToString(admin))
  println(format.encodeToString(guest))
}

And this time, we get the following results: 

{"type":"admin","userId":1,"userName":"Alice","adminRole":"Boss"}
{"type":"guest","userId":1,"userName":"Alice","guestEmail":"guest@email.com"}

We can serialize classes as long as we provide corresponding subclasses.

Of course, there is a lot to cover, for example, multiple superclasses or interfaces. But let’s stop here, maybe I’ll cover it explicitly in the other article. (Let me know if you are interested in this 🙂 )

Custom serializers

For some classes, happens that the default serialization method does not fulfill our needs. Or we want to create one that reflects a unique class utilization approach. For this purpose, custom serializers are our best friends. The most common examples are Date and Color. I’m gonna focus on Date.

Basically, there are 3 main parts of our custom serializer. Let’s check how the serializer for Date might look like:

object DateSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

We can already see all the necessary parts.

• The serialize function is used to turn an object into a sequence of simple values. It takes an Encoder and a value as inputs. It calls the encodeXxx functions of the Encoder to make the sequence. There is a different encodeXxx function for each simple type.
• The deserialize function is used to turn a sequence of simple values back into an object. It takes a Decoder as input and returns a value. It calls the decodeXxx functions of the Decoder to get the sequence. These functions match the encodeXxx functions of the Encoder.
• The descriptor property is used to tell how the encodeXxx and decodeXxx functions work. This helps the format to know what methods to use. Some formats can also use it to make a schema for the data.

For our purposes, we can simplify the class. If there is no particular need in the descriptor, we can use a @Serializer(forClass = …):

@Serializer(forClass = Date::class)
object DateSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

To implement our custom serializer we should use a @Serializable(with = …) annotation for the corresponding property:

@Serializable
data class Event(
  val name: String,
  @Serializable(with = DateSerializer::class)
  val date: Date
)

Let’s see that in action: 

val event = Event("Birthday Party", Date())  

val json = Json.encodeToString(event)  

println(json)

With the result: 

{"name":"Birthday Party","date":"2023-11-23 T 17:12:36.069+0300"}

As we can see, it has successfully been serialized to the desired date format.

Contextual serialization

Sometimes we need to change how we write objects as JSON at run-time, not just at compile-time, as we spoke before. This is called contextual serialization.

We can use the @Contextual annotation on a class or a property to tell Kotlin to use the ContextualSerializer class. This class will choose the right serializer for the object based on the context. We are going to use the previous serializer:

object DateAsStringSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

And our class will be looking like this:

@Serializable
data class Event(
  val name: String,
  @Contextual val date: Date
)

Now we need to create a SerializersModule in which we need to specify a serializers should be used for our contextually-serializable classes.

We can simply wrap our serializer in contextual function inside the module:

private val module = SerializersModule {
  contextual<Date>(DateAsStringSerializer)
}  

Now we create a format out of Json with our module:

val format = Json { serializersModule = module }

Using our format of Json earlier, we’ll get our run-time serialization: 

val event = Event("Birthday Party", Date())  

val json = format.encodeToString(event)  

println(json)

With an expected output: 

{"name":"Birthday Party","date":"2023-11-23 T 23:20:03.421+0300"}

kotlinx.serialization Summary

And that’s all for this article about serialization in Kotlin with kotlinx.serialization.

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 kotlinx, then you can find lots of useful information on the official documentation of kotlinx. 

The post kotlinx.serialization in Kotlin- All You Need To Know appeared first on Codersee blog- Kotlin on the backend.