Gitiles
Code Review Sign In
review.shift-gmbh.com / SHIFTPHONES / android_external_kotlinx.serialization / 778321f0161d0ffe98a715c31519f5550eff3edf
commit778321f0161d0ffe98a715c31519f5550eff3edf[log] [tgz]
authorSergey Shanshin <sergey.shanshin@jetbrains.com>Thu Aug 12 18:52:12 2021 +0300
committerGitHub <noreply@github.com>Thu Aug 12 18:52:12 2021 +0300
tree61a03f40dba47c67ae215e3de41ef6411979285c
parentf7a7141fd8c6080484a1b37b5ada2525cf28369e [diff]
Enum and onject serializer lookup tests (#1505)

Tests for #1386 :

* added `.serializer()` invoke for enums with generated and external serializers
* added tests on object's serializer lookup and `.serializer()` invoke
* added `assertFails` calls for platforms on which the lookup is broken and needs to be fixed in the future
3 files changed
tree: 61a03f40dba47c67ae215e3de41ef6411979285c
  1. .github/
  2. .idea/
  3. benchmark/
  4. bom/
  5. buildSrc/
  6. core/
  7. docs/
  8. dokka/
  9. formats/
  10. gradle/
  11. guide/
  12. integration-test/
  13. license/
  14. .gitignore
  15. build.gradle
  16. CHANGELOG.md
  17. CODE_OF_CONDUCT.md
  18. CONTRIBUTING.md
  19. gradle.properties
  20. gradlew
  21. gradlew.bat
  22. knit.properties
  23. LICENSE.txt
  24. README.md
  25. RELEASING.md
  26. settings.gradle
  27. update_docs.sh
README.md

Kotlin multiplatform / multi-format reflectionless serialization

official JetBrains project GitHub license TeamCity build Kotlin Maven Central KDoc link Slack channel

Kotlin serialization consists of a compiler plugin, that generates visitor code for serializable classes, runtime library with core serialization API and support libraries with various serialization formats.

  • Supports Kotlin classes marked as @Serializable and standard collections.
  • Provides JSON, Protobuf, CBOR, Hocon and Properties formats.
  • Complete multiplatform support: JVM, JS and Native.

Table of contents

Introduction and references

Here is a small example.

import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable 
data class Project(val name: String, val language: String)

fun main() {
    // Serializing objects
    val data = Project("kotlinx.serialization", "Kotlin")
    val string = Json.encodeToString(data)  
    println(string) // {"name":"kotlinx.serialization","language":"Kotlin"} 
    // Deserializing back into objects
    val obj = Json.decodeFromString<Project>(string)
    println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
}

You can get the full code here.

Read the Kotlin Serialization Guide for all details.

You can find auto-generated documentation website on GitHub Pages.

Setup

Kotlin serialization plugin is shipped with the Kotlin compiler distribution, and the IDEA plugin is bundled into the Kotlin plugin.

Using Kotlin Serialization requires Kotlin compiler 1.4.0 or higher. Make sure you have the corresponding Kotlin plugin installed in the IDE, no additional plugins for IDE are required.

Gradle

Using the plugins block

You can set up the serialization plugin with the Kotlin plugin using Gradle plugins DSL:

Kotlin DSL:

plugins {
    kotlin("jvm") version "1.5.20" // or kotlin("multiplatform") or any other kotlin plugin
    kotlin("plugin.serialization") version "1.5.20"
}

Groovy DSL:

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.5.20'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.5.20'
}

Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization

Using apply plugin (the old way)

First, you have to add the serialization plugin to your classpath as the other compiler plugins:

Kotlin DSL:

buildscript {
    repositories { mavenCentral() }

    dependencies {
        val kotlinVersion = "1.5.20"
        classpath(kotlin("gradle-plugin", version = kotlinVersion))
        classpath(kotlin("serialization", version = kotlinVersion))
    }
}

Groovy DSL:

buildscript {
    ext.kotlin_version = '1.5.20'
    repositories { mavenCentral() }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
    }
}

Then you can apply plugin (example in Groovy):

apply plugin: 'kotlin' // or 'kotlin-multiplatform' for multiplatform projects
apply plugin: 'kotlinx-serialization'

Dependency on the JSON library

After setting up the plugin one way or another, you have to add a dependency on the serialization library. Note that while the plugin has version the same as the compiler one, runtime library has different coordinates, repository and versioning.

Kotlin DSL:

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.2")
}

Groovy DSL:

repositories {
    mavenCentral()
}

dependencies {
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.2"
}

We also provide kotlinx-serialization-core artifact that contains all serialization API but does not have bundled serialization format with it

Android

Library should work on Android "as is". If you're using proguard, you need to add this to your proguard-rules.pro:

-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.AnnotationsKt # core serialization annotations

# kotlinx-serialization-json specific. Add this if you have java.lang.NoClassDefFoundError kotlinx.serialization.json.JsonObjectSerializer
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}

# Change here com.yourcompany.yourpackage
-keep,includedescriptorclasses class com.yourcompany.yourpackage.**$$serializer { *; } # <-- change package name to your app's
-keepclassmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
    *** Companion;
}
-keepclasseswithmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
    kotlinx.serialization.KSerializer serializer(...);
}

You may also want to keep all custom serializers you've defined.

Multiplatform (Common, JS, Native)

Most of the modules are also available for Kotlin/JS and Kotlin/Native. You can add dependency to the required module right to the common source set:

commonMain {
    dependencies {
        // Works as common dependency as well as the platform one
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serialization_version"
    }
}

The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.

Maven

Ensure the proper version of Kotlin and serialization version:

<properties>
    <kotlin.version>1.5.20</kotlin.version>
    <serialization.version>1.2.2</serialization.version>
</properties>

Add serialization plugin to Kotlin compiler plugin:

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <compilerPlugins>
                    <plugin>kotlinx-serialization</plugin>
                </compilerPlugins>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-serialization</artifactId>
                    <version>${kotlin.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Add dependency on serialization runtime library:

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-json</artifactId>
    <version>${serialization.version}</version>
</dependency>