Kotlin Serialization

Kotlin Serialization is Kotlin’s official multiplatform serialization library, using compile-time code generation instead of runtime reflection. JobRunr supports Kotlin Serialization through the KotlinxSerializationJsonMapper implementation, available in the jobrunr-kotlin-support.

Requirements

Kotlin Serialization support requires:

• JobRunr 8.0 or later
• jobrunr-kotlin-support

Note

Prior to JobRunr 8.5.0, the Kotlin support artifact was published as jobrunr-kotlin-[VERSION]-support ([VERSION] is to be replaced with a Kotlin version, e.g., 2.2).

Installation

Add both the Kotlin Serialization library and JobRunr’s Kotlin support package to your project.

Gradle (Kotlin DSL)

plugins {
  kotlin("plugin.serialization") version // ... specify your version
}

dependencies {
  // versions are omitted, use the latest versions
  implementation("org.jobrunr:jobrunr-kotlin-support")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json")
}

Note

We have not tested versions lower than 1.8.0 of kotlinx-serialization-json.

Usage

JobRunr automatically detects Kotlin Serialization on your classpath (checking for kotlinx.serialization.json.Json and org.jobrunr.kotlin.utils.mapper.KotlinxSerializationJsonMapper) and uses it for serialization. When multiple JSON libraries are available, Kotlin Serialization has the highest priority in the detection hierarchy.

Note

Pre JobRunr 8.4.0, unless you’re using one of the framework starters, KotlinxSerializationJsonMapper is not configured by default.

If auto-detection doesn’t work, you can manually configure it:

JobRunr.configure()
  .useJsonMapper(KotlinxSerializationJsonMapper())
  // ...
  .initialize()

import org.jobrunr.utils.mapper.JsonMapper

@Singleton
fun jsonMapper(): JsonMapper {
  return KotlinxSerializationJsonMapper()
}

import org.jobrunr.utils.mapper.JsonMapper

@Produces
fun jsonMapper(): JsonMapper {
  return KotlinxSerializationJsonMapper()
}

import org.jobrunr.utils.mapper.JsonMapper

@Bean
fun jsonMapper(): JsonMapper {
  return KotlinxSerializationJsonMapper()
}

Custom Kotlin Serialization configuration

Customize Kotlin Serialization by creating your own KotlinxSerializationJsonMapper instance. The class offers three constructors depending on your needs.

Important

Before proceeding, note that JobRunr may overwrite your custom configuration. Verify through testing that everything behaves as expected.

Using a custom SerializersModule

Pass a SerializersModule to register custom serializers for your domain types:

val customModule = SerializersModule {
  polymorphic(Notification::class) {
    subclass(EmailNotification::class)
    subclass(SmsNotification::class)
  }
}

val jsonMapper = KotlinxSerializationJsonMapper(customModule)

JobRunr combines your module with its own jobRunrSerializersModule, which includes serializers for Java types like Duration, Instant, and JobRunr-specific types.

Using a pre-configured Json instance

If you need full control over the Json configuration:

val json = Json {
  isLenient = true

  this.serializersModule = customModule + jobRunrSerializersModule
}

val jsonMapper = KotlinxSerializationJsonMapper(json)

Warning

Using a pre-configured Json instance bypasses JobRunr’s default configuration. Ensure your configuration includes necessary settings like classDiscriminator = "@class" for proper polymorphic serialization and that jobRunrSerializersModule is set.