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>
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