KtorサーバーでのWebSocketシリアライゼーション

コード例: server-websockets-serialization

ContentNegotiationプラグインと同様に、WebSocketでは、特定の形式でテキストフレームをシリアライズ/デシリアライズできます。Ktorは以下のフォーマットを標準でサポートしています。JSON、XML、CBOR、ProtoBuf。

依存関係の追加

kotlinx.serializationコンバーターを使用する前に、セットアップセクションに記載されている通り、Kotlinシリアライゼーションプラグインを追加する必要があります。

JSON

JSONデータをシリアライズ/デシリアライズするには、以下のライブラリのいずれかを選択できます。kotlinx.serialization、Gson、Jackson。

kotlinx.serializationGsonJackson

ビルドスクリプトにktor-serialization-kotlinx-jsonアーティファクトを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

ビルドスクリプトにktor-serialization-gsonアーティファクトを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

ビルドスクリプトにktor-serialization-jacksonアーティファクトを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

XML

XMLをシリアライズ/デシリアライズするには、ビルドスクリプトにktor-serialization-kotlinx-xmlを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

XMLシリアライゼーションは、jsNodeターゲットでサポートされていませんのでご注意ください。

CBOR

CBORをシリアライズ/デシリアライズするには、ビルドスクリプトにktor-serialization-kotlinx-cborを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

ProtoBuf

ProtoBufをシリアライズ/デシリアライズするには、ビルドスクリプトにktor-serialization-kotlinx-protobufを追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

シリアライザーの構成

JSONシリアライザー

kotlinx.serializationGsonJackson

WebSocketの設定でJSONシリアライザーを登録するには、Jsonパラメーターを指定してKotlinxWebsocketSerializationConverterインスタンスを作成し、このインスタンスをcontentConverterプロパティに割り当てます。

import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Json)
}

Gsonシリアライザーを登録するには、GsonWebsocketContentConverterをcontentConverterプロパティに割り当てます。

import io.ktor.serialization.gson.*

install(WebSockets) {
    contentConverter = GsonWebsocketContentConverter()
}

Jacksonシリアライザーを登録するには、JacksonWebsocketContentConverterをcontentConverterプロパティに割り当てます。

import io.ktor.serialization.jackson.*

install(WebSockets) {
    contentConverter = JacksonWebsocketContentConverter()
}

XMLシリアライザー

WebSocketの設定でXMLシリアライザーを登録するには、XMLパラメーターを指定してKotlinxWebsocketSerializationConverterインスタンスを作成し、このインスタンスをcontentConverterプロパティに割り当てます。

import nl.adaptivity.xmlutil.serialization.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(XML)
}

CBORシリアライザー

WebSocketの設定でCBORシリアライザーを登録するには、Cborパラメーターを指定してKotlinxWebsocketSerializationConverterインスタンスを作成し、このインスタンスをcontentConverterプロパティに割り当てます。

import io.ktor.serialization.kotlinx.cbor.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Cbor)
}

ProtoBufシリアライザー

WebSocketの設定でProtoBufシリアライザーを登録するには、ProtoBufパラメーターを指定してKotlinxWebsocketSerializationConverterインスタンスを作成し、このインスタンスをcontentConverterプロパティに割り当てます。

import kotlinx.serialization.protobuf.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(ProtoBuf)
}

データの受信と送信

データクラスの作成

フレームをオブジェクトに、またはオブジェクトからシリアライズ/デシリアライズするには、データクラスを作成する必要があります。例:

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

kotlinx.serializationを使用する場合、このクラスに@Serializableアノテーションが付いていることを確認してください。

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

データの受信

テキストフレームの内容を受信して変換するには、データクラスをパラメーターとして受け取るreceiveDeserialized関数を呼び出します。

webSocket("/customer") {
    val customer = receiveDeserialized<Customer>()
    println("A customer with id ${customer.id} is received by the server.")
}

incomingチャネルからデシリアライズされたフレームを受信するには、WebsocketContentConverter.deserialize関数を使用します。WebsocketContentConverterはWebSocketServerSession.converterプロパティを通じて利用可能です。

データの送信

指定されたフォーマットを使用してデータオブジェクトをテキストフレームで渡すには、sendSerialized関数を使用できます。

webSocket("/customer/1") {
    sendSerialized(Customer(1, "Jane", "Smith"))
}

完全な例はこちらで確認できます: server-websockets-serialization。