commit	d79fb1f70dad46b0edd3e311617555d24c11e3d7	[log] [tgz]
author	Leonid Startsev <sandwwraith@gmail.com>	Fri Sep 15 18:02:59 2017 +0300
committer	Leonid Startsev <sandwwraith@gmail.com>	Fri Sep 15 18:02:59 2017 +0300
tree	8ed23db8533ce13b40d705cbb3c9917dd5468edd
parent	1a8f683f5ba3df9b736ff803dbf9f912ba667bf4 [diff]

tree: 8ed23db8533ce13b40d705cbb3c9917dd5468edd

README.md

Kotlin serialization runtime library for JVM and JS

Kotlin serialization plugin consists of three parts: a gradle compiler plugin, an IntelliJ plugin and a runtime library. This is the runtime library. To build any project with serialization (including this one), you'll need a serialization gradle plugin. To have a proper syntax highlighting in the Intellij IDEA, you'll need an IDEA plugin.

Runtime library provides basic classes:

Interfaces which are called by compiler-generated code (KInput, KOutput)
Basic skeleton implementations of these interfaces in which you should override some methods if you want to implement custom data format (ElementValueInput/Output, NamedValueInput/Output, ElementValueTransformer)
Some internal classes like built-ins and collections serializers

Also, runtime library provides some ready-to-use serialization formats, see below.

Building and usage

From bintray

Public EAP is available at https://bintray.com/kotlin/kotlinx/kotlinx.serialization.runtime. It requires EAP compiler with version higher than 1.1.50. Example configuration for Gradle and Maven.

From source

Run ./gradlew publishToMavenLocal. After that, you can include this library in arbitrary projects like usual gradle dependency:

repositories {
    jcenter()
    mavenLocal()
}

dependencies {
    compile "org.jetbrains.kotlinx:kotlinx-serialization-runtime:0.1"
}

JavaScript

Replace kotlinx-serialization-runtime with kotlinx-serialization-runtime-js to use it in JavaScript projects. JavaScript example is located at example-js folder.

Example


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

@Serializable
data class Data(val a: Int, @Optional val b: String = "42")

fun main(args: Array<String>) {
    println(JSON.stringify(Data(42))) // {"a": 42, "b": "42"}
    val obj = JSON.parse<Data>("""{"a":42}""") // Data(a=42, b="42")
}

Detailed documentation with more complicated examples of usage located in DOC.md.

Example project with different implementations of custom formats can be found in examples folder. You can run it with cd examples; ./gradlew -q runApp.

Built-in formats

Runtime library provides three ready-to use formats: JSON, CBOR and ProtoBuf. Usage of the first two formats is pretty straightforward and obvious from the example above. Notes on them: because JSON doesn't support maps with keys other than strings (and primitives), Kotlin maps with non-trivial key types are serialized as JSON lists. CBOR doesn't have this limitation, and Kotlin maps are serialized as CBOR maps, but some parsers (like jackson-dataformat-cbor) don't support this.

Protobuf usage

Because protobuf relies on serial ids of fields, called 'tags', you have to provide this information, using serial annotation @SerialId:

@Serializable
data class KTestInt32(@SerialId(1) val a: Int)

This class is equivalent to the following proto definition:

message Int32 {
    required int32 a = 1;
}

Note that we are using proto2 semantics, where all fields are explicitly required or optional.

Number format is set via @ProtoType annotation. ProtoNumberType.DEFAULT is default varint encoding (intXX), SIGNED is signed ZigZag representation (sintXX), and FIXED is fixedXX type. uintXX and sfixedXX are not supported yet.

Repeated fields represented as lists. Because format spec says that if the list is empty, there will be no elements in the stream with such tag, you must explicitly mark any filed of list type with @Optional annotation with default = emptyList(). Same for maps.

Other known issues and limitations:

Packed repeated fields are not supported
Unknows fields aren't skipped, exception is thrown instead
If fields with list tag are going in the arbitrary order, they are not merged into one list, they got overwritten instead.

More examples of mappings from proto definitions to Koltin classes can be found in test data: here and here