Kotlin: Serialization

After chatting with Sebastiano Poggi about the issues with using Kotlin objects that I covered in a recent post, he made the interesting suggestion that possibly kotlinx.serialization might work better than the Java implementation because it is faster, more flexible (we can use different serialisation formats such as JSON or Protobuf), and is built with knowledge of the Kotlin language, so will possibly handle the singleton implementation of Kotlin objects better. This post covers some of the basics of Kotlin serialisation, and what was learned along the way.

As the name suggests, kotlinx.serialization is an equivalent to Java serialisation and there is much to like. One thing worth mentioning is that it is still very much a work in progress; It is still experimental and, as we shall see, is far from complete. At the time of writing (November 2019) I do not realistically see it hitting full release in the immediate future.

Let’s start by setting up our project to use kotlinx.serialization:

const val kotlinVersion = "1.3.50"

object BuildPlugins {
    const val kotlinGradlePlugin = "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
    const val kotlinSerializationPlugin = "org.jetbrains.kotlin:kotlin-serialization:$kotlinVersion"

    const val detekt = "io.gitlab.arturbosch.detekt"
    const val ktlint = "org.jlleitschuh.gradle.ktlint"
    const val versions = "com.github.ben-manes.versions"
    const val kotlinxSerialization = "kotlinx-serialization"
}

object Libraries {
    private object Versions {
        const val jupiter = "5.6.0-M1"
        const val kotlinxSerializationRuntime = "0.13.0"
    }

    const val kotlinStdLib = "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion"
    const val kotlinxSerializationRuntime =
        "org.jetbrains.kotlinx:kotlinx-serialization-runtime:${Versions.kotlinxSerializationRuntime}"
    const val jupiter = "org.junit.jupiter:junit-jupiter:${Versions.jupiter}"

}

buildscript {
    repositories {
        google()
        jcenter()
    }

    dependencies {
        classpath BuildPlugins.kotlinGradlePlugin
        classpath BuildPlugins.kotlinSerializationPlugin
    }
}

plugins {
    id 'com.github.ben-manes.versions' version '0.27.0'
    id 'io.gitlab.arturbosch.detekt' version "1.1.1"
    id 'org.jlleitschuh.gradle.ktlint' version '9.1.0'
    id 'org.jetbrains.kotlin.jvm' version '1.3.50'
}

apply plugin: BuildPlugins.versions
apply plugin: BuildPlugins.ktlint
apply plugin: BuildPlugins.detekt
apply plugin: BuildPlugins.kotlinxSerialization
.
.
.
dependencies {
    implementation Libraries.kotlinStdLib
    implementation Libraries.kotlinxSerializationRuntime
    testImplementation Libraries.jupiter
}
.
.
.

I felt that the best way of checking it was to apply it to the same class hierarchy as in the previous article:

@Serializable
sealed class KSerializerSealedClass {

    @Serializable
    object Object : KSerializerSealedClass()

    @Serializable
    object Object2 : KSerializerSealedClass()

    @Serializable
    data class DataClass(val data: String) : KSerializerSealedClass()
}

One of the fundamental principles of kotlinx.serialization is that we should be able to tag classes as being Serializable using the @Serializable annotation and the necessary serialisation code will be generated at compile time and will avoid the runtime performance issues of reflection-based approaches. So the overhead compared to Java serialisation is pretty minimal.

IMPORTANT UPDATE: The following is no longer true. With Kotlin 1.3.60+ and kotlinx.serialization 0.14.0+ Kotlin object serialisation is now supported. More details can be found here. Although the code for the rest of this article in no longer necessary for Kotlin object serialisation, it may be useful to those who need to write custom serialisers, so I have decided to leave it in place.

However, at the time of writing, Kotlin objects are not actually supported yet, and if we try this we’ll get compiler errors on Object and Object2:

@Serializable annotation is ignored because it is impossible to serialize automatically interfaces or enums. Provide serializer manually via e.g. companion object

This has changed – if you see this error then you should check that you’re using Kotlin 1.3.60 or later and kotlinx.serialization 0.14.0 or later.

I must confess that, at this point, I almost abandoned this idea because it felt like it would be better to wait until kotlinx.serialization fully supports Kotlin object serialisation. However, my curiosity wanted to understand what was necessary to actually get this working. While what follows will be obsolete once kotlinx.serialization fully supports Kotlin object serialisation, some of the principles are still quite useful – particularly when it comes to writing customer serializers , so there is still value in covering this.

It is worth mentioning that once it reaches a full release kotlinx.serialization will probably be as simple to implement as the above code (with perhaps some small changes), it’s just not there yet.

I had an initial stab at writing a custom serializer for Kotlin objects and it seemed like quite a lot of code. I decided to check with Eugenio Marletti who is a Developer Advocate at JetBrains whose knowledge of Kotlin is far more nuanced than mine. Eugenio confirmed that my technique was correct, but offered some great suggestions of how the code could be improved and compacted. The code that follows is basically my initially verbose code which has been cleaned up / improved by Eugenio.

Let’s start by looking at the enabler code. While there is only 12 lines of code here, there’s an awful lot going on:

interface ObjectSerializer : KSerializer {
    fun serializer() = this
}

inline fun  createObjectSerializer(crossinline instance: () -> T) =
    object : ObjectSerializer {
        override val descriptor: SerialDescriptor = SerialClassDescImpl(T::class.toString())
        override fun deserialize(decoder: Decoder) = instance()
        override fun serialize(encoder: Encoder, obj: T) {
            encoder.beginStructure(descriptor, this).endStructure(descriptor)
        }
    }

The ObjectSerializer interface is a generic extension of KSerializer (part of kotlinx.serialization) which adds a serializer() function. The value this gives us should be a little clearer once we see how it is implemented.

The createObjectSerializer is where a lot happens. This is the place where we do the main work required by KSerializer.

The descriptor is used as a key to this KSerializer implementation and needs to clearly identify that class that this KSerializer instance is responsible for. This is what the framework uses to find the correct KSerializer to use during deserialisation.

The deserialize() method defers the object deserialisation to the instance object passed in. This is actually doing the equivalent of the readResolve() implementation that we needed to do for Java serialisation in the previous article – it will always return instance when an object of this type is deserialised.

The serialise() method is responsible to writing the object – beginStructure() and endStructure() can be envisaged as XML:

    // T data goes here

The key thing here is the descriptor being written which enables the same deserializer to be called.

With these two enablers we can now update any / all objects within out project. In this case we update our class hierarchy:

sealed class KSerializerSealedClass {

    @Serializable(with = Object::class)
    object Object :
        KSerializerSealedClass(), ObjectSerializer