I/O ソースを用いた JSON のシリアライズ
Kotlin シリアライゼーションは、JVM ストリームや kotlinx-io、Okio の Source および Sink を操作するための API を提供しています。
これら API を使用することで、中間文字列を作成することなく、I/O ソースから直接 JSON のシリアライズおよびデシリアライズを行えます。 これらの API は UTF-8 エンコーディングを使用し、無効な JSON データに対しては SerializationException を、I/O 障害に対しては IOException をスローします。
I/O リソースを扱う際には、リソースリークを防ぐために適切にクローズすることが重要です。 操作が完了したときにリソースを自動的にクローズする .use() 関数を使用することで、これを行うことができます。
JVM 出力ストリームへの JSON のシリアライズ
JSON を JVM の OutputStream へ直接シリアライズするには、.encodeToStream() 拡張関数を使用します。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileOutputStream
@Serializable
data class Project(val name: String, val stars: Int)
fun main() {
val project = Project("kotlinx.serialization", 9000)
// project.json ファイルの OutputStream を作成
FileOutputStream("project.json").use { output ->
// project インスタンスを OutputStream にシリアライズ
Json.encodeToStream(project, output)
}
}この例では、Project の JSON 表現が project.json ファイルにシリアライズされます。
JVM 入力ストリームからの JSON のデシリアライズ
JVM の InputStream から直接 JSON をデシリアライズするには、.decodeFromStream() 拡張関数を使用します。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileInputStream
@Serializable
data class Project(val name: String, val stars: Int)
fun main() {
// InputStream をオープン
FileInputStream("project.json").use { input ->
// InputStream の JSON コンテンツを Project インスタンスにデシリアライズ
val project = Json.decodeFromStream<Project>(input)
// デシリアライズされた Project インスタンスを出力
println(project)
}
}この例では、入力ストリームの JSON コンテンツが単一の Project インスタンスにデシリアライズされます。
入力にトップレベルの JSON 配列内の複数の JSON オブジェクト、または空白で区切られた複数のオブジェクトが含まれている場合、.decodeToSequence() を使用して要素を遅延処理(lazy processing)できます。 これにより、パースされた値を順次処理できるようになります。例えば以下のようになります。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.io.FileInputStream
@Serializable
data class Project(val name: String, val stars: Int)
fun main() {
// Project オブジェクトの JSON 配列を含む projects.json ファイルの InputStream をオープン
FileInputStream("projects.json").use { input ->
// InputStream から各 Project を遅延デシリアライズ
val projects = Json.decodeToSequence<Project>(input)
// 要素を 1 つずつ処理
for (project in projects) {
println(project)
}
}
}.decodeToSequence() によって返されるシーケンスは、基となるストリームに結びついているため、一度しか反復処理(イテレート)できません。
シーケンスが完全に評価される前にその基となるストリームがクローズされた場合、シーケンスへのアクセス時に例外が発生することがあります。
kotlinx-io および Okio による JSON シリアライゼーション
JVM ストリームに加えて、kotlinx-io ライブラリ(現在は Alpha 段階)の kotlinx.io.Sink や kotlinx.io.Source、および Okio ライブラリの okio.BufferedSink や okio.BufferedSource などの I/O 型を使用して JSON を扱うこともできます。
これらの I/O 型を通じて JSON を直接読み書きするために、以下の Json 拡張関数を使用できます。
kotlinx.io.Sinkまたはokio.BufferedSinkに JSON を書き込むための.encodeToSink()および.encodeToBufferedSink()。kotlinx.io.Sourceまたはokio.BufferedSourceから単一の JSON 値を読み取るための.decodeFromSource()および.decodeFromBufferedSource()。- 複数の JSON 値を
Sequence<T>として遅延デコードするための.decodeSourceToSequence()および.decodeBufferedSourceToSequence()。
次のセクションでは、これらの API で kotlinx-io 型を使用する例を取り上げます。
Okio の型も同様に、対応する okio.BufferedSink および okio.BufferedSource API と組み合わせて使用できます。
kotlinx-io および Okio の依存関係の追加
kotlinx-io または Okio の型で拡張関数を使用するには、対応する依存関係を追加します。
kotlinx-io の依存関係の追加
// build.gradle(.kts)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-io:1.11.0")
implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.9.1")
}<!-- pom.xml -->
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-json-io</artifactId>
<version>1.11.0</version>
</dependency>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-io-core</artifactId>
<version>0.9.1</version>
</dependency>
</dependencies>Okio の依存関係の追加
// build.gradle(.kts)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-okio:1.11.0")
implementation("com.squareup.okio:okio:3.16.2")
}<!-- pom.xml -->
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-json-okio</artifactId>
<version>1.11.0</version>
</dependency>
<dependency>
<groupId>com.squareup.okio</groupId>
<artifactId>okio</artifactId>
<version>3.16.2</version>
</dependency>
</dependencies>Sink への JSON のシリアライズ
Sink に JSON をシリアライズするには、.encodeToSink() 関数を使用します。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// kotlinx-io の型および JSON I/O サポートの宣言をインポート
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*
@Serializable
data class Project(val name: String, val stars: Int)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
val project = Project("kotlinx.serialization", 9000)
// project.json ファイルの Sink を作成
val path = Path("project.json")
SystemFileSystem.sink(path).buffered().use { sink: Sink ->
// Project インスタンスを直接 Sink にシリアライズ
Json.encodeToSink(project, sink)
}
}Source からの JSON のデシリアライズ
Source から JSON をデシリアライズするには、.decodeFromSource() 関数を使用します。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// kotlinx-io の型および JSON I/O サポートの宣言をインポート
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*
@Serializable
data class Project(val name: String, val stars: Int)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
// project.json ファイルの Source をオープン
val path = Path("project.json")
SystemFileSystem.source(path).buffered().use { source: Source ->
// Source から直接 Project インスタンスにデシリアライズ
val project = Json.decodeFromSource<Project>(source)
println(project)
}
}入力に大きな JSON 配列や複数のトップレベル JSON オブジェクトが含まれている場合、.decodeSourceToSequence() 関数を使用することで、Source を遅延デコードされる Sequence<T> に変換できます。
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
// kotlinx-io の型および JSON I/O サポートの宣言をインポート
import kotlinx.serialization.json.io.*
import kotlinx.io.*
import kotlinx.io.files.*
@Serializable
data class Project(val name: String, val stars: Int)
@OptIn(ExperimentalSerializationApi::class)
fun main() {
// 複数の JSON オブジェクトを含む projects.json ファイルの Source をオープン
val path = Path("projects.json")
SystemFileSystem.source(path).buffered().use { source: Source ->
// Source から読み込まれる各 Project を遅延デシリアライズ
val projects: Sequence<Project> = Json.decodeSourceToSequence(source)
for (project in projects) {
println(project)
}
}
}.decodeSourceToSequence() によって返されるシーケンスは、基となる Source に結びついているため、一度しか反復処理(イテレート)できません。
シーケンスが完全に評価される前にその基となるソースがクローズされた場合、シーケンスへのアクセス時に例外が発生することがあります。
次のステップ
- シリアライズおよびデシリアライズのさまざまなユースケースに対応するために、Json インスタンスをカスタマイズする方法を学びます。
- パースやシリアライズを行う前に JSON データを操作・処理するための、高度な JSON 要素の取り扱いについて確認します。
- データをより柔軟に制御するために、シリアライズおよびデシリアライズ中に JSON を変換する方法を確認します。
