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.

Note: this article is based on my Complete Kotlin Course lesson, which I highly encourage you to check out if you are looking for a comprehensive Kotlin guide.

If this is your first meeting with DSLs, then I would recommend you to check out my other article, in which I explain and show how to implement Kotlin DSL step-by-step.

Video Tutorial

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

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

Uncontrolled Scope

But before we dive into the solution with Kotlin @DslMarker, let’s understand what problem it solves first.

So as the first step, let’s prepare a simple DSL with Board, Task, Author, and Comment classes:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

With the following Kotlin DSL implementation, we would expect that we could introduce different Boards, with Tasks inside them, which would have some Comments written by Authors.

But let’s take a look at the following code:

fun main() {
  val board = board {
    task {
      task {
        task {
          comment {
            task { }
            author {
              task { }
              comment {
                task { }
              }
            }
          }
        }
      }
    }
  }
}

Will it compile? Unfortunately, yes.

We invoke a task within a task, within a task, and so on. Moreover, we can invoke the task, or comment functions inside the author. 

And that’s because, by default, we can call the methods of every available receiver, which can lead to such situations. 

Kotlin @DslMarker To The Rescue

At this point, we already know what the issue is and what we will use to fix it.

But what exactly does the @DslMarker do in Kotlin?

Well, in practice, we use this annotation to introduce our new custom annotations. Then, we make use of them to mark classes and receivers, thus preventing receivers marked with the same annotation from being accessed inside one another.

This way, we won’t be able to access members of the outer receiver (like the task function, which is declared inside the Board class from the Task class instances).

Let’s consider the updated example:

@DslMarker
annotation class BoardDsl

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

@BoardDsl
class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

@BoardDsl
class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

@BoardDsl
class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

@BoardDsl
class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

fun main() {
  val board = board {
    task {  // OK
      task {  // Does not compile
        task {  // Does not compile
          comment {  // OK
            task { }  // Does not compile
            author {  // OK
              task { }  // Does not compile
              comment {  // Does not compile
                task { }  // Does not compile
              }
            }
          }
        }
      }
    }
  }
}

Firstly, we introduce the @BoardDsl annotation, which uses the @DslMarker.

Following, we must annotate every class in our hierarchy with our new annotation- this way, we make the Kotlin compiler “aware” of the hierarchy in our DSL.

Lastly, we can clearly see that the code will not compile whenever we try to nest the unwanted type inside another.

Scope Control With Kotlin @DslMarker Summary

Basically, that’s all for this tutorial on how to control scope when implementing a Kotlin DSL using the @DslMarker summary.

If you enjoy such a short, practice-focused learning approach then do not forget to check out my course and let me know in the comments section.

If you’d like to learn a bit more about the annotation itself, then the documentation may be useful to you too.

The post Scope Control With @DslMarker Annotation. Kotlin DSLs. appeared first on Codersee blog- Kotlin on the backend.

During this tutorial, we will learn:

• what are OpenAPI specs and what problem do they solve,
• why and when code generation might be a good idea for your project,
• how to generate Kotlin clients using different libraries, like Ktor, Retrofit, or Spring WebClient.

Video Tutorial

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

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

What are OpenAPI Specs

OpenAPI, formerly known as Swagger, is a specification for describing and documenting RESTful APIs.

Imagine that each person or team would describe created APIs in their own, custom manner. Confluence pages, READMEs, text files, graphic charts, and many many more. Probably millions of different ways to describe the same thing.

Thankfully, OpenAPI solves this problem and allows us to describe and document HTTP APIs in a standardized manner so that both the creators and consumers can be on the same page.

What does it look like? Well, let’s take a look at the example we will be working with today:

openapi: 3.0.0
info:
  version: 1.0.0
  title: JSON Placeholder API
  description: See https://jsonplaceholder.typicode.com/
paths:
  /posts:
    get:
      description: Returns all posts
      tags: ["Posts"]
      operationId: "getPosts"
      responses:
        "200":
          description: Successful response
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PostsList"

  /posts/{id}:
    get:
      description: Returns a post by id
      tags: ["Posts"]
      operationId: "getPost"
      parameters:
        - name: id
          in: path
          required: true
          description: The user id.
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Successful response
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Post"
        "404":
          description: Post not found

components:
  schemas:
    PostsList:
      "type": "array"
      "items":
        $ref: "#/components/schemas/Post"
    Post:
      "type": "object"
      "required":
        - "id"
        - "userId"
        - "title"
      "properties":
        id:
          type: "integer"
        userId:
          type: "integer"
        title:
          type: "string"
        completed:
          type: "boolean"

As we can see, the OpenAPI spec is a YAML file (but can be a JSON too) which is a language-agnostic instruction of the API.

Moreover, given its standardized structure and format, it can be easily read not only by humans, but machines too, which we will see in this article in action 🙂

When And Why Code Generation Might Be A Good Idea?

As software engineers, we automate things, so that they can be done faster, easier, and with less amount of errors.

You probably see where I’m going now 🙂

Whenever we do things manually, we need more time, we make more mistakes, and we distract ourselves from things that we are actually good at.

And among plenty of areas in our codebase, HTTP clients might be a good place to start with. This is the area, where the only thing that we care about is fetching/sending the data in an appropriate format, and where we end up with lots of boilerplate code.

Solution- OpenAPI Generator

And in order to generate a client in Kotlin we can use the OpenAPI generator.

And although in this article we will focus on the clients, this generator can be used to create servers and documentation for over 50 languages and frameworks, too. If you would like to check the full list, then you can find it right here.

But how exactly it is going to help us?

Well, in simple words, with this tool we can convert the OpenAPI specification file into the ready-to-use Kotlin classes with WebClient/OkHTTP/Retrofit implementation of HTTP clients and data classes for response and request objects.

Generate Kotlin Client- Gradle

One of the easiest ways to add the OpenAPI generator to our codebase will be the Gradle plugin.

Let’s navigate to the build.gradle.kts file and add the following:

plugins {
    // other plugins
    id("org.openapi.generator") version "7.0.1"
}

Nextly, let’s sync our project.

When it’s done, we will see the following tasks added to our project:

• openApiGenerate– to generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents,
• openApiGenerators– to lists generators available via Open API Generators,
• openApiMeta– to generate a new generator to be consumed via Open API Generator,
• openApiValidate– which we can use to validate an Open API 2.0 or 3.x specification document.

Add OpenAPI Spec To The Project

As the next step, let’s add the OpenAPI spec to the project.

In our example, we will use the json-placeholder-api.yaml file we saw already and put it inside the $root/openapi directory.

Following, let’s navigate to build.gradle.kts and alter the openApiGenerate task:

openApiGenerate {
    inputSpec.set("$rootDir/openapi/json-placeholder-api.yaml")
    generatorName.set("kotlin")
}

The above configs are the only two required settings: we need to specify the input spec and the generator we would like to use.

Note: at the moment, we can specify only one input spec (and quite possible it will be already fixed by the time you will read this blog post). But if that’s not the case, then you can use the merger plugin.

And if you are wondering what library will the “Kotlin” generator use by default, then at the moment of writing, it is OkHttp 4.2.0.

Change the HTTP Client Library

But can we change the HTTP client library? Yes, of course.

We can use one of the following instead:

• jvm-ktor
• jvm-okhttp4 (default)
• jvm-okhttp3
• jvm-spring-webclient
• jvm-retrofit2
• multiplatform
• jvm-volley
• jvm-vertx

And the only thing we need to do with our gradle plugin is to set the library property:

openApiGenerate {
    inputSpec.set("$rootDir/openapi/json-placeholder-api.yaml")
    generatorName.set("kotlin")

    library.set("jvm-retrofit2")
}

Of course, we can customize plenty of other settings in the OpenAPI generator plugin. To see the whole list of available properties, please refer to the Kotlin generator docs.

Moreover, it’s worth mentioning that the generator plugin does not import necessary dependencies to the project. It is our responsibility and depending on the library we need to add them to the project.

For example, when dealing with the default client we must import okhttp3 and moshi:

dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.11.0")
    implementation("com.squareup.moshi:moshi:1.15.0")
    implementation("com.squareup.moshi:moshi-kotlin:1.15.0")

    #other dependencies
}

Using Generated Code

With all of that being done, let’s run the openApiGenerate task, for example, using the gradle wrapper:

 ./gradlew openApiGenerate

By default, our tool puts all the files inside the $root/build/generate-resources/src directory.

Moreover, the default package name is main.kotlin.org.openapitools.client, which of course can be customized according to our needs.

When we check the content, we should see plenty of files generated for us:

Of course, this will vary depending on the library we use, but for Retrofit, we will see among others this:

import okhttp3.Call
import okhttp3.Interceptor
import okhttp3.OkHttpClient
import retrofit2.Retrofit
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Converter
import retrofit2.CallAdapter
import retrofit2.converter.scalars.ScalarsConverterFactory
import com.squareup.moshi.Moshi
import retrofit2.converter.moshi.MoshiConverterFactory


class ApiClient(
    private var baseUrl: String = defaultBasePath,
    private val okHttpClientBuilder: OkHttpClient.Builder? = null,
    private val serializerBuilder: Moshi.Builder = Serializer.moshiBuilder,
    private val callFactory : Call.Factory? = null,
    private val callAdapterFactories: List<CallAdapter.Factory> = listOf(
    ),
    private val converterFactories: List<Converter.Factory> = listOf(
        ScalarsConverterFactory.create(),
        MoshiConverterFactory.create(serializerBuilder.build()),
    )
) {
 // code
}

And the interface handling two endpoints:

import org.openapitools.client.infrastructure.CollectionFormats.*
import retrofit2.http.*
import retrofit2.Call
import okhttp3.RequestBody
import com.squareup.moshi.Json

import org.openapitools.client.models.Post

interface PostsApi {
    /**
     * 
     * Returns a post by id
     * Responses:
     *  - 200: Successful response
     *  - 404: Post not found
     *
     * @param id The user id.
     * @return [Call]<[Post]>
     */
    @GET("posts/{id}")
    fun getPost(@Path("id") id: kotlin.Long): Call<Post>

    /**
     * 
     * Returns all posts
     * Responses:
     *  - 200: Successful response
     *
     * @return [Call]<[kotlin.collections.List<Post>]>
     */
    @GET("posts")
    fun getPosts(): Call<kotlin.collections.List<Post>>

}

Can we start using it already? Not really.

If we try to use these classes now in our code, they won’t be found.

In gradle, we must add the generated directory to the sourceSets:

sourceSets {
    main {
        java {
            srcDir("${buildDir}/generate-resources/main/src")
        }
    }
}

And with that done, we can finally make use of the code:

import org.openapitools.client.apis.PostsApi

fun main() {
  val api = PostsApi(basePath = "https://jsonplaceholder.typicode.com")

  api.getPosts()
    .forEach(::println)
}

Make Generation a Part of Compilation

Before I wrap this article, I would like to show you one more thing.

Whenever we try to run the code without the generated files, it will fail. There’s no point of doing that manually each time either.

So, as a solution, we can alter the compileKotlin flow:

tasks.compileKotlin{
    dependsOn("openApiGenerate")
}

In simple words, the openApiGenerate task will be always invoked before the compileKotlin.

Summary

And that’s all for this article on how to generate a Kotlin HTTP client using the OpenAPI generator.

I hope that this introduction will convince you to give it a try and will be a good help in your first steps.

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

Have a great week and don’t forget to leave a comment 🙂

The post Generate Kotlin Client From OpenAPI Specs appeared first on Codersee blog- Kotlin on the backend.

Hi! If you’ve ever been wondering how to implement a custom Trifunction in Kotlin, then you just came to the right place.

In this, short article we will cover the following:

• what is a TriFunction?
• what is a functional interface and how can we implement it in Kotlin?
• how can we utilize SAM conversions to make our code more concise?
• and finally- a slightly different approach, which may be better in some cases.

Video Tutorial

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

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

2. What is a Functional Interface?

Let’s start with defining what exactly is a functional interface.

Well, it is nothing else than an interface with exactly one abstract method.

In Kotlin, we can define it using the fun keyword:

fun interface MyFunctionalInterface {
  fun method()
  fun anotherMethod() // Compilation Error!

  // OK!
  fun nonAbstractMethod() {

  }
}

As we can see, such interfaces can have multiple non-abstract members.

However, the code won’t compile whenever we try to implement more than one abstract method:

Fun interfaces must have exactly one abstract method

3. TriFunction and Kotlin Implementation

The TriFunction interface is nothing else than a functional interface with three input parameters and one output.

To better understand it, let’s take a look at the following code:

fun interface CustomTriFunction<T, U, V, R> {
  fun someFun(t: T, u: U, v: V): R
}

In this example, we declare a generic functional interface CustomTriFunction with exactly one abstract function- someFun.

This function has 3 parameters of type T, U, and V, and returns a value of type R.

4. Test Function

Following, let’s declare an example test function:

fun <T, U, V, R> example(
  t: T,
  u: U,
  v: V,
  function: CustomTriFunction<T, U, V, R>,
): R {
  val result = function.someFun(t, u, v)
  // some logic here
  return result
}

As we can see, the example is a generic function, which we will invoke with 3 values, and as the last one, we will pass the implementation of CustomTriFunction.

And although this example is a bit trivial, we may want to use this strategy in real-life scenarios to keep our code open for extension and closed for modification.

5. Implementation No 1- Class

With all of that done, we can finally use the interface and implement the code responsible for invoking the example.

Let’s start with the most basic idea- adding a new class:

class CustomImplementation : CustomTriFunction<String, Long, Int, Double> {
  override fun someFun(t: String, u: Long, v: Int): Double {
    // some logic
    return 10.0
  }
}

The above code shouldn’t be surprising even if we are pretty new to Kotlin.

We implement the CustomTriFunction just like every generic interface and provide the body for someFun.

Nextly, the only thing we need to do is to create a new instance of our class and pass it as the last argument:

val customImplementation = CustomImplementation()
val result = exampleOne("", 0L, 0, customImplementation)

Of course, depending on our case the CustomImplementation could be a Kotlin object.

6. Idea 2- Anonymous Object

But sometimes, we don’t want to explicitly define a new class. Maybe we want to pass a very specific logic, which definitely won’t be used anywhere else in the code.

For such a one-time operation, we can use the anonymous object:

val anonymousObject = object : CustomTriFunction<String, Long, Int, Double> {
  override fun someFun(t: String, u: Long, v: Int): Double {
    return 10.0
  }
}
val result = exampleOne("", 0L, 0, anonymousObject)

As we can see, the instance of an anonymous object (also known as an anonymous class) looks almost the same, as in the previous example. With one, important difference- it does not have a name.

And as I mentioned previously- this approach may be really helpful for one-time use.

7. Implementation 3 (Better)- SAM Conversion

In Kotlin, functional interfaces are also known as Single Abstract Method (SAM) interfaces.

And instead of defining anonymous objects, we can make use of SAM conversions, which allow us to use lambda expressions instead:

val samConversionOne = CustomTriFunction { t: String, u: Long, v: Int -> 10.0 }
val resultOne = exampleOne("", 0L, 0, samConversionOne)

// or alternatively:
val samConversionTwo = CustomTriFunction<String, Long, Int, Double> { t, u, v -> 10.0 }
val resultTwo = exampleOne("", 0L, 0, samConversionTwo)

// or even:
val resultThree = exampleOne("", 0L, 0) { t, u, v -> 10.0 }

// Note: in Kotlin, if the last argument is a function,
// we can put it outside of round brackets- (). 

With a SAM conversion, Kotlin can convert any lambda expression whose signature matches the signature of the interface’s single method into the code, which dynamically instantiates the interface implementation.

Source: https://kotlinlang.org/docs/fun-interfaces.html#sam-conversions

And to put it simply, with this approach we can implement our TriFunction in a much more concise manner (which is often the case with Kotlin ;).

8. Approach 4- High-Order Function Without Interface

As the last example, let’s take a look at the high-order function.

In Kotlin, a high-order function is a function, which takes another function as an argument or returns a function.

So at the end of the day, instead of explicitly creating a custom TriFunction interface, we can define a parameter of function type:

fun <T, U, V, R> example(
  t: T,
  u: U,
  v: V,
  function: (T, U, V) -> R,
): R {
  val result = function.invoke(t, u, v) // or simply function(t, u, v)
  // some logic here
  return result
}

As we can see, the function parameter simply informs the compiler that we expect a function with three input arguments (T, U, V) and return type R.

And then, we can invoke it by passing a lambda to it:

val lambda = { t: String, u: Long, v: Int -> 10.0 }
val result = example("", 0L, 0, lambda)

// or even: 
val result = exampleTwo("", 0L, 0) { t, u, v -> 10.0 }

And this approach might be a great choice whenever we would like to have a TriFunction without explicitly defining a new interface.

9. Summary

And that’s all for this article about how to implement the Kotlin TriFunction interface in Kotlin.

I hope you enjoy my content and if you’d like to learn more about Kotlin and support my work, then I highly encourage you to check my Kotlin Handbook Course.

The post How To Implement TriFunction in Kotlin? appeared first on Codersee blog- Kotlin on the backend.

Hi! 🙂 In this publication, we will learn how to implement statically-typed, type-safe Kotlin builders which we can use to implement our own DSLs.

Firstly, we will discuss what exactly DSLs are, their benefits, and why Kotlin is a good choice for creating them. Then, we will learn more about function literals with a receiver. And finally, we will put together all this knowledge and implement our own DSL.

Note: This article has been created based on my course Kotlin Handbook. Learn Through Practice. If you are looking for high-quality, step-by-step Kotlin learning path, then you should definitely check it out.

Video Tutorial

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

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

2. What is a DSL?

A DSL is an acronym for Domain-Specific Language.

It’s nothing else than a specialized language designed to solve problems or tasks within a specific domain.

Unlike general-purpose languages (like Kotlin itself), which are designed for a wide range of applications, DSLs focus on easy-to-understand syntax tailored to a particular problem domain.

Great examples can be:

• HTML for creating web pages,
• Gradle for building automation,
• or SQL for querying databases.

3. The Purpose and Benefits of DSLs

The main purpose of DSLs is to help programmers to deal with complex hierarchical data structures in an easy way. 

So, a well-designed domain-specific language provides (among others) the following benefits: 

• expressiveness– helps us to express complex ideas and logic using a more concise and natural syntax,
• readability– the code we produce is simply easier to read and understand, 
• maintainability– a modular, and organized code structure makes it easier to maintain and extend our programs. 

4. Is Kotlin a Good Choice For DSLs?

Short answer- yes. 

Kotlin is designed to be a concise, readable, and expressive programming language. When we combine together properly named functions and function literals with receiver, we can implement truly type-safe Kotlin builders.

Additionally, lambda expressions, scoping literals, extension, or infix functions help us to organize everything in an even cleaner way.

If you are looking for real-life usage examples, then we can find type-safe builders for example, when configuring routes in Ktor, or in Gradle’s Kotlin DSL.

5. Function Literals with Receiver

With all of that being said, let’s start the practice part by explaining the concept of function literals with receiver.

In simple words, it is nothing else than a combination of lambda expression:

val hello: (String) -> String = { name -> "Hello, $name" }

fun main() {
  val greeting = hello("Pjoter")
  
  println(greeting)  // Hello, Pjoter
}

And extension function:

fun String.hello() : String = "Hello, $this"

fun main() {
  val greeting = "Pjoter".hello()
  
  println(greeting)  // Hello, Pjoter
}

Which combined together form:

val hello: String.() -> String = { "Hello, $this" }

fun main() {
  val greeting = "Pjoter".hello()
  
  println(greeting)  // Hello, Pjoter
}

In our example, the String object, for which we invoke the function is a receiver and it implicitly becomes this inside the function. This way, we can access all its members, like public fields, inside our function (even without this keyword).

Great, but how does this relate to creating DSLs in Kotlin?

Well, we can pass function literals with receiver as arguments to high-order functions (functions that take other functions as parameters).

I know, a mumbo jumbo, but everything will become clear by the end of this tutorial 😉

6. Implement Custom Kotlin DSL

6.1 Add High-Order Function

As the first step, let’s take a look at the example class:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
}

fun main() {
  val board = Board()
  board.title = "Important Tasks"
  board.color = BoardColor.GREEN
}

Nothing spectacular, right? Just a simple class with mutable properties.

So as the next step, let’s add a higher-order function, which expects the function literal with a receiver as an argument:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
}

fun board(init: Board.() -> Unit): Board {
  val board = Board()
  board.init()
  return board
}

fun main() {
  val board = board {
    title = "Important Tasks"
    color = BoardColor.GREEN
  }
}

The board function is pretty straightforward- firstly, we create a new Board instance, and then we invoke the init function on it. After that, we return the updated object instance.

When we look at the main function, we can see that the only thing we do is the board function invocation.

But there is no parenthesis- “()”- right?

Well, technically we could use them: board ( {/*some code*/ } ). But in Kotlin, when the last parameter of a function is a function, then a lambda expression passed as the corresponding argument can be placed outside the parentheses (docs). In our case- the function has only one parameter, so we don’t need parenthesis, at all.

6.2 Kotlin Type-Safe Builder

And although at this point our logic looks like overkill, life isn’t always that easy and we may need to add more hierarchy to our code.

Let’s consider the following code snippet:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Task {
  var title: String = ""
  var description: String = ""
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  var tasks: MutableList<Task> = mutableListOf()
}

fun main() {
  val taskOne = Task() 
  taskOne.title = "Task 1"
  taskOne.description = "Task 1 description"  
  
  val taskTwo = Task() 
  taskTwo.title = "Task 2"
  taskTwo.description = "Task 2 description"   
  
  val tasks = mutableListOf(taskOne, taskTwo)  
    
  val board = Board() 
  board.title = "Important Tasks"
  board.color = BoardColor.GREEN
  board.tasks = tasks	  
}

In this case, every Board object can contain multiple Tasks instances.

When we look at the main function, it’s pretty hard to see the hierarchy of objects at first glance.

And now, let’s analyze the Kotlin type-safe builder approach:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Task {
  var title: String = ""
  var description: String = ""
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  var tasks: MutableList<Task> = mutableListOf()
  
  fun task(init: Task.() -> Unit) {
    val task = Task()
    task.init()
    tasks.add(task)
  }
}

fun board(init: Board.() -> Unit): Board {
  val board = Board()
  board.init()
  return board
}

fun main() {
   val board = board {
     title = "Important Tasks"
     color = BoardColor.GREEN
    
     task {
       title = "Task 1"
       description = "Task 1 description"  
     }
    
     task {
       title = "Task 2"
       description = "Task 2 description" 
     }
  }  
}

We brought back the board function and implemented a new task method inside the Board.

When we implement our lambda inside the main function, we can access the task function, just like we access the title, or color property of the Board object.

To better visualize, let’s use the explicit this and parenthesis:

val board = board {
  this.title = "Important Tasks"
  this.color = BoardColor.GREEN
    
  this.task( {
    this.title = "Task 1"
    this.description = "Task 1 description"  
  } )
    
  this.task( {
    this.title = "Task 2"
    this.description = "Task 2 description" 
  } )
}  

To rephrase- the object, for which we invoke the function is a receiver and it implicitly becomes this inside the function.

So, our board function first creates a new object and then invokes passed lambda on it- which sets the title, color and invokes the task method twice.

On the other hand, the task function also creates a new, “plain” object and also invokes passed lambda on it- this time, setting the title and description values for it.

And basically, we’ve just created our first, simple Kotlin type-safe builder 🙂

7. Summary

In this article, we’ve learned not only how to create our custom Kotlin DSL, but also the key features which make this possible.

Of course, this is just an introduction, and if you are interested in learning more, for example about scope control, then let me know in the comments section 🙂

The post Kotlin Type-Safe Builders Explained. Implement Your Own DSL. appeared first on Codersee blog- Kotlin on the backend.

In this article, I will show you what exactly Kotlin operator overloading is, how we can use it, and what’s even more important- what value can it bring to your project?

Video Tutorial

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

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

2. What is Kotlin Operator Overloading?

Well, operator overloading is nothing else, than a possibility to provide a custom implementation for a predefined set of operators on Kotlin types.

Let’s take a look at the following example:

data class Example(
    val value: Int
) {
  operator fun plus(otherValue: Int): Example =
    Example(this.value + otherValue)
}

fun main(args: Array<String>) {
  val example = Example(10)
  val addedExample = example + 11
  addedExample // Example(value=21)
}

When working with Kotlin, we can implement our own plus operator function, and later simply make use of the + sign in our code. (And of course, this is only one of the many operators we can work with).

What’s worth mentioning here is that we can implement our operator using both member functions and extension functions:

operator fun Example.plus(otherValue: Int): Example =
  Example(this.value + otherValue)

And I am well aware that this feature will never be a deal-breaker when selecting the right programming language for your project. Nevertheless, I still think that when properly used, it can help us maintain code readability and achieve a more expressive and natural codebase.

3. Invoke Operator

With all of that being said, let’s start the practice part and learn Kotlin operator overloading.

And as the first one, let’s take a look at the invoke operator, which simply translates parenthesis into the call to the invoke function:

class SomeHandler {
    operator fun invoke(): String = "Some String"
    operator fun invoke(value: String): String = "Some String with String value: $value"
    operator fun invoke(value: Int): String = "Some String with Int value: $value"
}

fun main(args: Array<String>) { 
  val handler = SomeHandler()

  handler()        // Some String
  handler("one")   // Some String with String value: one
  handler(1)       // Some String with Int value: 1
}

As we can see, with this approach we don’t have to specify the function name anymore. When dealing with classes, which truly have a single responsibility and a descriptive name, this becomes an interesting syntactic sugar.

Of course, when overriding invoke() we can implement functions taking multiple arguments, as well.

4. Unary Operators

Nextly, let’s take a look at unary operators:

• +someVariable -> someVariable.unaryPlus()
• -someVariable -> someVariable.unaryMinus()
• !someVariable -> someVariable.not()
• ++someVariable / someVariable++ -> someVariable.inc()
• -- someVariable / someVariable-- -> someVariable.dec()

Note: when incrementing/decrementing we have to remember about the way postfix and prefix approach differ. In a moment, I will show you an example.

So, let’s see an example class with the first 3 operators:

data class SomeText(
    val value: String
) {
    operator fun unaryPlus(): SomeText =
        SomeText(this.value.uppercase())

    operator fun unaryMinus(): SomeText =
        SomeText(this.value.lowercase())

    operator fun not(): SomeText =
        SomeText(this.value.reversed())
}

fun main(args: Array<String>) { 
  val someText = SomeText("This is My text")

  +someText // SomeText(value=THIS IS MY TEXT)
  -someText // SomeText(value=this is my text)
  !someText // SomeText(value=txet yM si sihT)
}

This time, for each unary operator, we simply return a new instance with an appropriately modified value.

When it comes to the inc() and dec(), the class implementation looks, as follows:

data class CustomPoint(
    val x: Int,
    val y: Int
) {
  operator fun inc(): CustomPoint =
    CustomPoint(this.x + 1, this.y + 1)

  operator fun dec(): CustomPoint =
    CustomPoint(this.x - 1, this.y - 1)
}

And although this looks just like a previous example, this time we have to return instances o CustomPoint in both cases.

Additionally, there’s a bit of a “magic” happening depending on whether we decide to use a suffix or prefix form:

fun main(args: Array<String>) { 
  var point = CustomPoint(0, 0)

  ++point    // CustomPoint(x=1, y=1)
  point++    // CustomPoint(x=1, y=1)
  point      // CustomPoint(x=2, y=2)
  --point    // CustomPoint(x=1, y=1)
  point--    // CustomPoint(x=1, y=1)
  point      // CustomPoint(x=0, y=0)
}

So basically:

• when using the prefix form, the inc()/dec() function is invoked first and then the result is simply returned,
• however, when using the suffix form, then the result is firstly stored in temporary storage, returned as a result of the expression, and assigned to the initial variable.

5. Binary Operators

Following, let’s learn operator overloading with Kotlin binary operators.

As an example, let’s learn how do the comparison work:

• x < y -> x.compareTo(y) < 0
• x > y -> x.compareTo(y) > 0
• x <= y -> x.compareTo(y) <= 0
• x >= y -> x.compareTo(y) >= 0

So, our previously implemented class- SomeText– can be a great candidate for that:

data class SomeText(
    val value: String
) {
  operator fun compareTo(other: SomeText): Int {
    val thisLength = this.value.length
    val otherLength = other.value.length

    return thisLength - otherLength
  }
}

fun main(args: Array<String>) { 
  val textA = SomeText("123")
  val textB = SomeText("456")

  textA > textB  // false
  textA < textB // false 
  textA >= textB // true
  textA <= textB // true
}

As we can see, with such a simple approach the code become much more readable and intuitive.

Of course, there are much more binary (and not only) Kotlin operators, which we can use for operator overloading and I will add a link to the documentation at the end of this article.

6. Infix Notation

And although the infix notation is technically not a part of operator overloading, I feel obliged to mention it.

Basically, the infix notation is nothing else than the possibility to implement custom infix operations. And even though they do not bring as much, as the operators overloading, I still believe they are a pretty good syntactic sugar.

Let’s take a look at the following code:

data class SomeText(
    val value: String
) {
  infix fun codersee(other: SomeText): SomeText =
    SomeText("Codersee ${this.value}, ${other.value}")

  infix fun codersee(other: String): String =
    "Codersee ${this.value}, $other"
}

fun main(args: Array<String>) { 
  val anotherText = SomeText("another")
  
  anotherText codersee SomeText("value")   // SomeText(value=Codersee another, value)
  anotherText codersee "value"             // "Codersee another, value"
}

This time, we can see that instead of invoking the anotherText.codersee(), we can simply use an infix notation.

Nevertheless, we have to keep in mind some limitations:

• they must have only one parameter,
• and the parameter itself cannot accept a variable number of arguments and or have a default value.

7. Kotlin Operator Overloading Summary

And that’s all for this article about Kotlin operator overloading and what this feature brings to the table. As promised, right here you can find the documentation, where you can learn more about this functionality.

Lastly, if you enjoyed this article, then you might want to check out my other Kotlin articles.

The post How Can Kotlin Operator Overloading Help You? appeared first on Codersee blog- Kotlin on the backend.

If you would like to learn:

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

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

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

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

One more thing…

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

Thank you for your time and have a great week!

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

Hello friend :D. In this article, I would like to show you how Kotlin when expression works.

After reading this post, you will precisely:

• know what is Kotlin when and what are the differences when used as an expression or statement,
• when does the else branch is mandatory,
• how does it work with enums and sealed classes,
• how can we replace the if-else-if block with it, make use of smart casts, and many more…

2. What is Kotlin When?

With that being said, let’s start with answering the question- what exactly the Kotlin when is?

Basically, it’s a conditional expression, which lets us specify more than two branches. Just like with if we can specify what should happen when the expression is either true or false, Kotlin when lets us do the same for many expressions.

Its basic syntax looks, as follows:

when (someNumber) {
  1 -> println("Value is equal to 1.")
  2 -> println("Value is equal to 2.")
  3 -> println("Value is equal to 3.")
  else -> println("Value is greater than 3.")
}

As we can see, if the value is equal to 1, 2, or 3, then the appropriate println statement is invoked. Otherwise, the “Value is greater than 3.” text will be printed.

3. Is The Else Branch Mandatory?

As the next step, let’s answer the question: is the else branch mandatory? The answer is- not always– and here comes the explanation.

So, the Kotlin when can be used as either:

• expression- simply, when the result of a branch is returned, for example, assigned to a variable,
• or a statement- when it does not return any value.

When we use it as an expression, we have to make our compiler “happy” that all possibilities are covered (exhausted).

To get a better understanding, let’s look at the following snippet:

// Simple statement:
when(someNumber) {
  1 -> "Value is 1"
}

// Expression:
val someText = when(someNumber) {
  1 -> "Value is 1"
  else -> "Value is not 1"
}

As we can see, in the first case we have a simple statement, which means that it works without the else branch. On the other hand, in the second case, we have to provide the else branch, because otherwise, the code will not compile with the following error:

Kotlin: ‘when’ expression must be exhaustive, add necessary ‘else’ branch.

To rephrase it in an even more human way- if we want to assign some String value to the someText variable based on our Kotlin when instruction we have to make sure that the compiler will always be 100% sure, what value it should assign. In the code snippet above, the someNumber can be whatever number. What String value should the compiler assign if we do handle only one case without the else branch? What if the someNumber will be let’s say 23? And that’s the main reason why the else branch is mandatory in such a case.

4. Exhaustive Kotlin When

But with that in mind, we have to remember that in Kotlin there are a few possibilities to make branches exhaustive without the else branch:

• enums – we can specify a branch for each value of the enum class,
• sealed classes – we can handle each subclass separately,
• booleans – simply replacing else with false will be exhausting.

Let’s see a couple of examples below.

4.1. Kotlin When With Enum Class

As the first one, let’s take a look at the Kotlin enum class:

enum class UserType {
  STANDARD, MANAGER, ADMIN
}

fun getUserTypeLabel(userType: UserType): String =
  when (userType) {
    UserType.STANDARD -> "Standard User"
    UserType.MANAGER -> "Manager User"
    UserType.ADMIN -> "Admin User"
  }

As we can see, when we cover each enum value, the compiler has no “doubts” about what String value should be returned.

Nevertheless, please keep in mind that we will have to update this function if we add more values to our enum class.

4.2. Kotlin When With Sealed Class

Nextly, let’s see the example with a sealed class:

sealed class User

class StandardUser: User()
class ManagerUser: User()
class AdminUser: User()

fun printAndReturnText(user: User) : String =
  when (user) {
    is StandardUser -> {
      println("It was a Standard User.")
      "Standard User"
    }
    is ManagerUser -> {
      println("It was a Manager.")
      "Manager User"
    }
    is AdminUser -> {
      println("It was an Admin.")
      "Admin User"
    }
}

Similarly, all possibilities are covered and logic is invoked based on the subclass type.

Furthermore, there’s one interesting thing happening here- a smart cast, and we will get back to it later.

4.3. When Expression With Boolean

Finally, let’s check an example with a Boolean value:

val someBoolean = true

val someText = when (someBoolean) {
  true -> "It's true."
  false -> "It's false."
}

Although we used a false as a second branch here, we could achieve the same with an else in this particular case.

5. Kotlin When Smart Cast

At 4.2., I’ve mentioned one of the coolest things in Kotlin when expression- smart casts (you can read more about them later right here).

Let’s rewrite our example a bit and add a few functions to classes:

sealed class User

class StandardUser : User() {
  fun onlyStandardUserFunction() {}
}

class ManagerUser : User()
class AdminUser : User() {
  fun onlyAdminFunction() {}
  fun onlyAdminFunction2() {}
}

With that being done, our when expression can look, as follows:

fun printAndReturnText(user: User): String =
  when (user) {
    is StandardUser -> {
      user.onlyStandardUserFunction()
      "Standard User"
    }
    is ManagerUser -> {
      "Manager User"
    }
    is AdminUser -> {
      user.onlyAdminFunction()
      user.onlyAdminFunction2()
      "Admin User"
    }
}

As can be seen, our user instance has been automatically casted to the desired types. To put it simply, when the compiler checks that the user is an instance of AdminUser class, we can use its functions without casting.

So that this:

is AdminUser -> {
  user.onlyAdminFunction()
  user.onlyAdminFunction2()
  "Admin User"
}

Can be done without this:

is AdminUser -> {
  (user as AdminUser).onlyAdminFunction()
  (user as AdminUser).onlyAdminFunction2()
  "Admin User"
}

It’s worth mentioning here, that we can do that with any class, not only with sealed class instances:

fun someFunction(argument: Any) {
  when (argument) {
    is Int -> {
      val subtracted = argument.minus(2)
      println(subtracted)
    }
    is String -> {
      val upperCase = argument.uppercase()
      println(upperCase)
    }
  }
}

As we can see, when the argument is of an Int type, we can invoke a minus function. Alternatively, when it’s a String, we can transform it to upper case.

6. Kotlin When As if-else-if Replacement

As you might have already noticed, in the above examples all branches were invoked based on the same check.

But that’s not always the case. When creating an if-else-if statement, we can perform completely different comparisons:

if (someNumber == 1)
  println("Value is equal to 1.")
else if (anotherNumber == 55 && someText == "some")
  println("Completely differentn comparison.")
else
  println("Else branch invoked.")

As we can see, we do check for completely different conditions, and based on them the appropriate logic is executed.

But can we do the same with a Kotlin when (not switch! :D) statement? Of course, we do. The above logic can be rewritten to:

when {
  someNumber == 1 -> "Value is equal to 1."
  anotherNumber == 55 && someText == "some" -> println("Value is equal to 2.")
  else -> println("Value is greater than 3.")
}

Please note, that this time we don’t have the expression inside the curly braces. Moreover, the else branch could be skipped in this particular case (and if you know why, please type a comment! 😀 ).

7. Kotlin When Variable

As the last thing, I would like to show you one more case.

The Kotlin when expression allows us to assign our check result to a variable, which then can be used inside the when. Moreover, this particular variable scope will be limited to the when expression only.

And again, this might sound confusing, so let’s see an example:

when (val someNumber = 10) {
  10 -> {
    val anotherNumber = someNumber * 10
    println(anotherNumber)
  }
  else -> {
    val anotherNumber = someNumber - 10
    println(anotherNumber)
  }
}
val someNumber = 20  // No conflicting declaration error

As we can see, we declare the someNumber inside the curly braces and we can then utilize it inside our branches. Finally, we can declare a variable with exactly the same name just right after the when expression.

9. Summary

And that would be all for this article on the “Kotlin switch… ekhm.. when expression”.

Let me know whether you enjoyed it and whether you would like to see more core Kotlin articles in the comment section below.

Finally, as a reminder, if you’d like to check your Kotlin knowledge, you can visit my quizzes page.

The post Kotlin switch… ekhm.. when expression appeared first on Codersee blog- Kotlin on the backend.

In this article, I would like to introduce you to the concept of data classes in Kotlin and how they can help you in your day-to-day coding. Together, we will learn their purpose, possibilities and a few rules we have to remember about when using them.

2. What Are Data Classes and Why Do We Need Them?

Oftentimes, when implementing any program we may encounter the need for a class, which main purpose will be holding and transferring the data. Database queries results might be a great example here.

For such a case, the creators of Kotlin came up with data classes:

data class Person(val name: String, val age: Int)

Although we can’t see it, adding a data word before a standard Kotlin class results in a few functions being generated automatically:

• equals() and hashCode()
• toString()
• copy()
• component1()…componentN() – for each property declared in the primary constructor

Given these points, data classes allow us to write less verbose, less error-prone and easier to maintain code.

2.1. equals() and hashCode()

With that being said, let’s have a look at the first two functions- equals() and hashCode():

val firstPerson = Person("Peter", 40)
val secondPerson = Person("Peter", 40)

println(firstPerson.hashCode()) //-1907803204
println(secondPerson.hashCode()) //-1907803204

println(firstPerson == secondPerson)// true

As we can clearly see, both functions work, as expected and the hashCode for two structurally equal instances is exactly the same.

If you would like to learn a bit more about Kotlin equality, then I highly recommend this article from their official documentation.

2.2. toString()

As the next step, let’s let’s have a look at the toString():

val person = Person("John", 20)

println(person) // Person(name=John, age=20)

As can be seen, the default Kotlin toString() implementation uses the following format:

ClassName(propertyOne=valueOne, propertyTwo=valueTwo)

2.3. copy()

Nextly, let’s check out the copy() function, which allows us to create a new instance of a data class changing some of its properties:

val beforeCopying = Person("Peter", 30)
val afterCopying = beforeCopying.copy(
    age = 35
)

println(beforeCopying === afterCopying)  // false
println(afterCopying)  // Person(name=Peter, age=35)

A copy function created a totally new instance of Person class (referential equality === returning false is a proof for that) with age set to a new value.

From the technical side, the copy implementation for our class would be as follows:

fun copy(name: String = this.name, age: Int = this.age) = Person(name, age)

2.4. Destructuring Declarations with componentN() Functions

Finally, let’s take a while to understand componentN() functions.

As I’ve mentioned previously, such a function will be generated for each property declared in the primary constructor:

data class Person(val name: String, val age: Int) {
    lateinit var email: String
}

val person = Person("John", 20)

val personName = person.component1()  // John
val personAge = person.component2()   // 20
val personEmail = person.component3() // ERROR

As we can see, we can reference to the Person name and age using component1() and component2() functions (and yes, in case of more properties, functions component3()… etc. would be generated).

However, the most important thing here is that these functions allow us to destructure an object into variables:

val person = Person("John", 20)

val (personName, personAge) = person
println(personName)
println(personAge)

This syntax in Kotlin is called a destructuring declaration and allows us to keep our code even more concise.

If you would like to learn a bit more about it, then I recommend this article from JetBrains.

3. Data Classes Limitations and Behaviour

So for now, we’ve learned what data classes are in Kotlin and what do they bring to the table. Nevertheless, we have to keep in mind that there are a few rules we have to remember about when working with them.

In this chapter, I will walk you through all of them.

3.1. Open, Sealed, Abstract, Inner

First of all, data classes cannot be open, sealed or abstract. If we declare it with either of them, the code won’t compile informing us with the following message:

Modifier ‘XYZ’ is incompatible with ‘data’

3.2. Primary Constructor

Nextly, we have to remember that primary constructor has to contain at least one parameter:

class One()      // OK
data class Two() // ERROR

As we can see, the second line will result in a pretty descriptive error thrown:

Data class must have at least one primary constructor parameter

Whatsoever, all primary constructors has to be marked as val or var, so the following code:

data class Person(var name: String, age: Int)

Will lead us to again to the compilation error:

Data class primary constructor must have only property (val / var) parameters.

3.3. copy() and componentN() Implementations

Following, we have to keep in mind that we can’t implement our own copy() and componentN() implementations.

data class Person(val name: String, val age: Int) {
    fun copy(
        name: String = this.name,
        age: Int = this.age
    ) = Person(name, age)
    
    fun component1() : String = ""
}

As we can see, both declarations will prohibit our code from compiling because of the conflicting overloads.

On the other hand, we can provide our custom implementation for toString(), hashCode() and equals() functions.

3.4. Default Constructor

Another thing worth remembering when working with JVM is that we have to specify default values for all properties if we would like the default constructor to be generated:

// default constructor won't be generated
data class One(val name: String = "", val age: Int)
// default constructor generated underneath
data class Two(val name: String = "", val age: Int = 0)

Although it might seem like a trifle, some libraries might require us to do so to work properly. A good example here is Jackson and “No Creators, like default construct, exist” error

3.5 Inheritance

Finally, let’s see a few rules related to the inheritance:

• first of all, data classes in Kotlin can extend other classes (although cannot be open)
• secondly, please keep in mind that if the superclass contains a final implementation for toString(), hashCode() or equals(), then none of them will be generated in our data class
• lastly, if the supertype declares open componentN() functions with incompatibile types, then the error will be thrown

4. Summary

And that would be all for this article covering data classes in Kotlin. I know, that all these rules and limitations above seem like plenty of things to deal with, but trust me, you won’t event notice them in real-life scenarios. Data classes are a great feature in Kotlin and sooner or later you will find them useful and this article is definitely worth bookmarking.

I would be happy if you would like to spend one minute and let me know if such materials are useful for you in the comments section or with the contact form.

The post All You Need To Know About Data Classes in Kotlin appeared first on Codersee blog- Kotlin on the backend.