Ktor Server での WebSockets シリアライズ

コード例: server-websockets-serialization

ContentNegotiation プラグインと同様に、WebSockets では特定のフォーマットでテキストフレームをシリアライズ/デシリアライズできます。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

WebSockets の設定で 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 シリアライザー

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

import nl.adaptivity.xmlutil.serialization.*

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

CBOR シリアライザー

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

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

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

ProtoBuf シリアライザー

WebSockets の設定で 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。