JSON functionality for ktor
This library provides ktor integration for the json-kotlin
library.
In the Application
module function, use:
install(ContentNegotiation) {
jsonKtor {}
}
Customizations (e.g custom serialization or deserialization) may be specified within the lambda supplied to the
jsonKtor
function:
install(ContentNegotiation) {
jsonKtor {
fromJSON { json ->
require(json is JSONObject) { "Must be JSONObject" }
Example(json.getString("custom1"), json.getInt("custom2"))
}
}
}
For more details see the json-kotlin
library.
From version 0.6 onwards, this library uses the json-streaming
library for on-the-fly JSON parsing.
This means that the input data is parsed into an internal form as it is being read, and avoids the need to allocate
memory for the entire JSON text.
From version 0.10, the library will stream asynchronously to a Kotlin Flow
or ReceiveChannel
, using the Kotlin
coroutine functionality.
If the data stream consists of a data array (a sequence of objects in square brackets), it may be deserialized as
follows:
val flowInput = call.receive<Flow<BusinessObject>>()
flowInput.collect { businessObject ->
// process businessObject
}
Or (slightly more complicated):
val channel = call.receive<ReceiveChannel<BusinessObject>>()
while (!channel.isClosedForReceive) {
val businessObject = channel.receive()
// process businessObject
}
From version 1.1, the library will (optionally) stream output using a non-blocking output library
(json-kotlin-nonblocking
).
Using this option, ktor response data will be sent as soon as it is available - this is particularly useful when data is
produced asynchronously:
val result = flow<BusinessObject> {
val businessObject = businessFunction()
emit(businessObject)
}
call.respond(result)
Or:
val result = scope.produce<BusinessObject> {
val businessObject = businessFunction()
send(businessObject)
}
call.respond(result)
Because there is a performance penalty for using streamed output, this is an option that must be enabled in the
JSONConfig
:
install(ContentNegotiation) {
jsonKtor {
streamOutput = true
}
}
Version 1.0 (and later) of this library uses ktor version 1.3.0.
This release of ktor introduced a number of breaking changes, and earlier versions of ktor will not work with
json-ktor
1.0 and above.
Anyone requiring ktor 1.2.4 support will need to use json-ktor
version 0.10.
Version 1.2 and later of this library uses ktor version 1.4.0.
The latest version of the library is 1.4, and it may be obtained from the Maven Central repository.
<dependency>
<groupId>net.pwall.json</groupId>
<artifactId>json-ktor</artifactId>
<version>1.4</version>
</dependency>
implementation 'net.pwall.json:json-ktor:1.4'
implementation("net.pwall.json:json-ktor:1.4")
Peter Wall
2023-07-12