A concise and lightweight Kotlin DSL to build JSON objects and render their String representations
Using no other dependency than Kotlin
Available on Maven Central
Now part of Awesome Kotlin !
// for an empty object
obj { }
// for an object
obj {
"attribute" to 42
"another" to true
}
// for an empty array
arr
// for an array
arr["element", 12.345, null]|
Note
|
Any combination of these elements is possible |
val obj = obj {
"key" to 3.4
"anotherKey" to arr["test", "test2", 1, 2.433, true]
"nullValue" to null
"emptyObject" to obj { }
"emptyArray" to arr
"custom" to ZonedDateTime.now()
}
println(obj) (1)
println(obj.pretty()) (2)(1)
{"key":3.4,"anotherKey":["test","test2",1,2.433,true],"nullValue":null,"emptyObject":{},"emptyArray":[],"custom":"2020-07-15T10:59:19.042965+02:00[Europe/Paris]"}
(2)
{
"key": 3.4,
"anotherKey": [
"test",
"test2",
1,
2.433,
true
],
"nullValue": null,
"emptyObject": {
},
"emptyArray": [
],
"custom": "2020-07-15T10:59:19.042965+02:00[Europe/Paris]"
}val array = arr[
"example",
obj {
"apple" to "pie"
"key" to 3.14
"anotherKey" to arr["first", "second", 1, 2.433, true]
}
]
println(array) (1)
println(array.pretty()) (2)(1)
["example",{"apple":"pie","key":3.14,"anotherKey":["first","second",1,2.433,true]}]
(2)
[
"example",
{
"apple": "pie",
"key": 3.14,
"anotherKey": [
"first",
"second",
1,
2.433,
true
]
}
]If you wish so, you can inline multiple entries in obj using Kotlin’s optional statement separator ; semicolon
obj { "key" to 3.4; "another" to true }You can provide any Iterable, thus Collection to feed in an array arr
arr[listOf("element", 12.345, null)]
arr[setOf("element", 12.345, null)]When using the pretty() method on obj or arr, you can define the number of whitespaces used for tabulation.Default value is 2.
// "compact", single line mode
obj { ... }
// 2 whitespaces tabulation
obj { ... }.pretty()
// 3 whitespaces tabulation
arr[ ... ].pretty(3)-
A JSON key (attribute) can only be of
KotlintypeString(will render escaping",\and\nchars)
|
Note
|
In IntelliJ, a compilation error will appear, and code will be flagged as not reachable |
-
A JSON value of an obj { } or an arr[…] can be one of the following
Kotlinor Koson DSL instances-
obj { }
-
arr[…]
-
arr (empty array)
-
String?(will render escaping",\and\nchars) -
Number? -
Boolean? -
null -
Any?(will render using.toString(), escaping",\and\nchars) -
YourType : CustomKoson, will render using.serialize(). (See next section for details) -
rawJson("{…}") (will render as is). (See section below)
-
If you don’t want to rely on the default toString() that would be used on an Any?, you can provide an instance that implements the CustomKoson interface.
You’ll then need to override the serialize(): KosonType method.
|
Tip
|
The KosonType return type should either be an obj or an arr
|
class Person(
val firstName: String,
val lastName: String,
val age: Int
) : CustomKoson {
override fun serialize() = obj {
"usualName" to "$firstName $lastName"
"age" to age
}
}If you know what content will be rendered upfront, you should favor using DSL elements to build your Json.
However, sometimes you may need to include an external source of Json.
You can use the rawJson(validJson: String?) method to do so.
obj {
"rawContent" to rawJson(externalJsonSource())
}|
Warning
|
You need to ensure the parameter Beware that rendering will not escape |
|
Note
|
pretty() will not work on rawJson Strings, however toString() will inline provided content
|
Benchmarks have been conducted with the jmh OpenJDK tool.Benchmark project can be found under benchmarks folder.
Two tests were done with the same objects and arrays
-
Rendering a big object (String representation)
-
Rendering a big array (String representation)
Koson was put side to side with one of the most popular JSON builder for Java : JSON-java
Testing environment : 3.3 GHz Intel Core i5-6600, 4 cores, VM version: OpenJDK 11.0.1, 64-Bit Server VM, 11.0.1+13
| Benchmark | Score | Error | Units |
|---|---|---|---|
BigObject - JSON-java |
17120,661 |
± 45,741 |
ops/s |
BigObject - Koson |
17433,982 |
± 372,361 |
ops/s |
BigObject (pretty) - JSON-java |
8902,486 |
± 19,417 |
ops/s |
BigObject (pretty) - Koson |
10252,254 |
± 71,377 |
ops/s |
BigArray - JSON-java |
15272,946 |
± 139,435 |
ops/s |
BigArray - Koson |
14816,130 |
± 132,266 |
ops/s |
BigArray (pretty) - JSON-java |
7744,935 |
± 41,067 |
ops/s |
BigArray (pretty) - Koson |
8607,388 |
± 31,712 |
ops/s |
To run the tests locally with java 8 or later, do
cd benchmarks
mvn package
java -jar target/benchmarks.jar