FasterXML / FasterXML/jackson-module-kotlin

Improve serialization performance of value classes that require only unboxing.

Open
#715 5 comments 0 reactions 0 assignees View on GitHub
2.17 enhancement value class
Dominant language
Kotlin
Stars
1.2k
Forks
187
Avg merge
9h 48m
Merged PRs (30d)
16

Description

The name of the annotation to be introduced are currently under discussion.
`JsonKUnbox` is the current first choice.

Please refer to the exchange in the comments for restrictions on naming.
If you have a better name, please suggest it.

---

### Use case

In `jackson-module-kotlin`, when serializing a `value class`, even if it is unboxed, the procedure is to box it once and unbox it again if necessary.
This is necessary to enable features such as `JsonValue` and custom serializers.

Since this is done at each serialization call, the performance is greatly reduced compared to using a normal class (`data class` + `JsonValue`).
[Verification with `kogera`](https://github.com/ProjectMapK/kogera-benchmark#normal) confirms this(Although `kogera` is strictly a different project, there are no major differences in processing).
![image](https://github.com/FasterXML/jackson-module-kotlin/assets/24751011/63ec952f-8290-4016-bd27-bd3667238505)

On the other hand, the main use case for the `value class` would be to simply output the `unboxed` value.
In that case, these overheads are completely useless.

### Describe the solution you'd like

I am thinking of providing some way to skip those processes if only unboxing is required.

In my personal experimental project `jackson-module-kogera`, I implemented a way to specify it by means of an annotation named `JsonUnbox`.
https://github.com/ProjectMapK/jackson-module-kogera/blob/develop/src/main/kotlin/io/github/projectmapk/jackson/module/kogera/annotation/JsonUnbox.kt

This annotation is used by attaching it to a `value class` or a `property getter` that returns a `value class`.
https://github.com/ProjectMapK/jackson-module-kogera/blob/e9111c22124f789b66ac0201ce8d8a1156b24110/src/test/kotlin/io/github/projectmapk/jackson/module/kogera/_integration/ser/value_class/json_unbox/ForClass.kt#L9-L11
https://github.com/ProjectMapK/jackson-module-kogera/blob/e9111c22124f789b66ac0201ce8d8a1156b24110/src/test/kotlin/io/github/projectmapk/jackson/module/kogera/_integration/ser/value_class/json_unbox/ForProperty.kt#L18-L39

This is included in [2.15.2-beta5](https://github.com/ProjectMapK/jackson-module-kogera/releases/tag/2.15.2-beta5).

[Benchmarking](https://github.com/ProjectMapK/kogera-benchmark#with-jsonunbox) confirms that it can provide better performance than `data class` + `JsonValue`.
![image](https://github.com/FasterXML/jackson-module-kotlin/assets/24751011/e21e7855-511c-4464-8604-367f51139148)

I also considered adding an option to limit the basic behavior regarding `value class` to unboxing, but have not worked on it yet as it would be more difficult to implement.

### Additional context

I am considering implementing the `JsonUnbox` annotation on the `jackson 2.17` target.

Please post any other requests for the name or behavior of this annotation, or for `value class` serialization performance improvements, to this issue.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.