Ktor 3.0.0-rc-1 Help

WebSockets serialization

Similar to the ContentNegotiation plugin, WebSockets allow you to serialize/deserialize text frames in a specific format. The Ktor client supports the following formats out-of-the-box: JSON, XML, CBOR, and ProtoBuf.

Add dependencies

Before using kotlinx.serialization converters, you need to add the Kotlin serialization plugin as described in the Setup section.

JSON

To serialize/deserialize JSON data, you can choose one of the following libraries: kotlinx.serialization, Gson, or Jackson.

Add the ktor-serialization-kotlinx-json artifact in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-json:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Add the ktor-serialization-gson artifact in the build script:

implementation("io.ktor:ktor-serialization-gson:$ktor_version")
implementation "io.ktor:ktor-serialization-gson:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-gson-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Add the ktor-serialization-jackson artifact in the build script:

implementation("io.ktor:ktor-serialization-jackson:$ktor_version")
implementation "io.ktor:ktor-serialization-jackson:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-jackson-jvm</artifactId> <version>${ktor_version}</version> </dependency>

XML

To serialize/deserialize XML, add the ktor-serialization-kotlinx-xml in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-xml:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-xml:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId> <version>${ktor_version}</version> </dependency>

CBOR

To serialize/deserialize CBOR, add the ktor-serialization-kotlinx-cbor in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-cbor:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId> <version>${ktor_version}</version> </dependency>

ProtoBuf

To serialize/deserialize ProtoBuf, add the ktor-serialization-kotlinx-protobuf in the build script:

implementation("io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version")
implementation "io.ktor:ktor-serialization-kotlinx-protobuf:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Configure a serializer

JSON serializer

To register the JSON serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Json parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.* import kotlinx.serialization.json.* val client = HttpClient(CIO) { install(WebSockets) { contentConverter = KotlinxWebsocketSerializationConverter(Json) } }

To register the Gson serializer, assign GsonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.gson.* install(WebSockets) { contentConverter = GsonWebsocketContentConverter() }

To register the Jackson serializer, assign JacksonWebsocketContentConverter to the contentConverter property:

import io.ktor.serialization.jackson.* install(WebSockets) { contentConverter = JacksonWebsocketContentConverter() }

XML serializer

To register the XML serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the XML parameter and assign this instance to the contentConverter property:

import nl.adaptivity.xmlutil.serialization.* install(WebSockets) { contentConverter = KotlinxWebsocketSerializationConverter(XML) }

CBOR serializer

To register the CBOR serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the Cbor parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.cbor.* install(WebSockets) { contentConverter = KotlinxWebsocketSerializationConverter(Cbor) }

ProtoBuf serializer

To register the ProtoBuf serializer in the WebSockets configuration, create a KotlinxWebsocketSerializationConverter instance with the ProtoBuf parameter and assign this instance to the contentConverter property:

import io.ktor.serialization.kotlinx.protobuf.* install(WebSockets) { contentConverter = KotlinxWebsocketSerializationConverter(ProtoBuf) }

Receive and send data

Create a data class

To serialize/deserialize text frames into/from an object, you need to create a data class, for example:

data class Customer(val id: Int, val firstName: String, val lastName: String)

If you use kotlinx.serialization, make sure that this class has the @Serializable annotation:

@Serializable data class Customer(val id: Int, val firstName: String, val lastName: String)

To learn more about kotlinx.serialization, see the Kotlin Serialization Guide.

Send data

To send a class instance within a text frame in a specified format, use the sendSerialized function:

client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer") { sendSerialized(Customer(1, "Jane", "Smith")) }

Receive data

To receive and convert a content of a text frame, call the receiveDeserialized function that accepts a data class as a parameter:

client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer/1") { val customer = receiveDeserialized<Customer>() println("A customer with id ${customer.id} is received by the client.") }

To receive deserialized frames from the incoming channel, use the WebsocketContentConverter.deserialize function. WebsocketContentConverter is available via the DefaultClientWebSocketSession.converter property.

Last modified: 02 April 2024