Merge pull request #154 from ProjectMapK/feat/json-unboxed

Added `JsonUnbox` annotation to improve `value class` serialization performance

Author: k163377

docs/AboutValueClassSupport.md

@@ -43,6 +43,14 @@ The same policy applies to deserialization.
 This policy was decided with reference to the behavior as of `jackson-module-kotlin 2.14.1` and [kotlinx-serialization](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/value-classes.md#serializable-value-classes).  
 However, these are just basic policies, and the behavior can be overridden with `JsonSerializer` or `JsonDeserializer`.
 
+### Serialization performance improvement using `JsonUnbox`
+In `jackson-module-kogera`, the `jackson` functionality is modified by reflection so that the `Jackson` functionality works for `value class` as well.
+These are executed on all calls.
+On the other hand, if only `unbox` is required, these are extra overheads that can significantly impair serialization performance.
+
+Therefore, `jackson-module-kogera` provides the `JsonUnbox` annotation.
+When this annotation is provided, serialization performance is improved because only calls to `getter` that is `unboxed` will be made.
+
 ## For features that would not be supported
 I do not intend to support features that require significant effort to support and that can be circumvented by user definition.
 

docs/KogeraSpecificImplementations.md

@@ -25,3 +25,7 @@ I will consider making the classes public again when we receive requests for the
 ## Remove old options and `deprecated` code
 Because `jackson-module-kotlin` is a framework with a long history, some old code and options remain.  
 In `kogera`, those options have been removed.
+
+# Value class support
+The `jackson-module-kogera` supports many use cases of `value class` (`inline class`).  
+This is summarized [here](./AboutValueClassSupport.md).

src/main/kotlin/io/github/projectmapk/jackson/module/kogera/annotation/JsonUnbox.kt

@@ -0,0 +1,12 @@
+package io.github.projectmapk.jackson.module.kogera.annotation
+
+/**
+ * Only affects properties that return value class and value class.
+ * If given, parsing to apply `Jackson` features will be skipped and only unbox will be performed.
+ * This will prevent various features such as JsonValue and custom serializers from working,
+ * but will improve serialization performance.
+ */
+@Retention(AnnotationRetention.RUNTIME)
+@MustBeDocumented
+@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY_GETTER)
+public annotation class JsonUnbox

src/main/kotlin/io/github/projectmapk/jackson/module/kogera/annotation_introspector/KotlinFallbackAnnotationIntrospector.kt

@@ -12,6 +12,7 @@ import com.fasterxml.jackson.databind.util.Converter
 import io.github.projectmapk.jackson.module.kogera.KotlinDuration
 import io.github.projectmapk.jackson.module.kogera.ReflectionCache
 import io.github.projectmapk.jackson.module.kogera.ValueClassUnboxConverter
+import io.github.projectmapk.jackson.module.kogera.annotation.JsonUnbox
 import io.github.projectmapk.jackson.module.kogera.deser.CollectionValueStrictNullChecksConverter
 import io.github.projectmapk.jackson.module.kogera.deser.MapValueStrictNullChecksConverter
 import io.github.projectmapk.jackson.module.kogera.isNullable
@@ -83,7 +84,12 @@ internal class KotlinFallbackAnnotationIntrospector(
                     KotlinDurationValueToJavaDurationConverter
                 }
             } else {
-                cache.getValueClassBoxConverter(a.rawReturnType, it)
+                // If JsonUnbox is specified, the unboxed getter is used as is.
+                if (a.hasAnnotation(JsonUnbox::class.java) || it.getAnnotation(JsonUnbox::class.java) != null) {
+                    null
+                } else {
+                    cache.getValueClassBoxConverter(a.rawReturnType, it)
+                }
             }
         }
         is AnnotatedClass -> lookupKotlinTypeConverter(a)

src/test/kotlin/io/github/projectmapk/jackson/module/kogera/_integration/ser/value_class/json_unbox/ForClass.kt

@@ -0,0 +1,42 @@
+package io.github.projectmapk.jackson.module.kogera._integration.ser.value_class.json_unbox
+
+import io.github.projectmapk.jackson.module.kogera.annotation.JsonUnbox
+import io.github.projectmapk.jackson.module.kogera.jacksonObjectMapper
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+
+class ForClass {
+    @JvmInline
+    @JsonUnbox
+    value class Primitive(val v: Int)
+
+    @JvmInline
+    @JsonUnbox
+    value class NonNullObject(val v: String)
+
+    @JvmInline
+    @JsonUnbox
+    value class NullableObject(val v: String?)
+
+    data class Dto(
+        val p0: Primitive = Primitive(0),
+        val p1: Primitive? = Primitive(1),
+        val p2: Primitive? = null,
+        val nno0: NonNullObject = NonNullObject("0"),
+        val nno1: NonNullObject? = NonNullObject("1"),
+        val nno2: NonNullObject? = null,
+        val no0: NullableObject = NullableObject("0"),
+        val no1: NullableObject = NullableObject(null),
+        val no2: NullableObject? = NullableObject("2"),
+        val no3: NullableObject? = null
+    )
+
+    @Test
+    fun test() {
+        val expected =
+            """{"p0":0,"p1":1,"p2":null,"nno0":"0","nno1":"1","nno2":null,"no0":"0","no1":null,"no2":"2","no3":null}"""
+        val actual = jacksonObjectMapper().writeValueAsString(Dto())
+
+        assertEquals(expected, actual)
+    }
+}

src/test/kotlin/io/github/projectmapk/jackson/module/kogera/_integration/ser/value_class/json_unbox/ForProperty.kt

@@ -0,0 +1,49 @@
+package io.github.projectmapk.jackson.module.kogera._integration.ser.value_class.json_unbox
+
+import io.github.projectmapk.jackson.module.kogera.annotation.JsonUnbox
+import io.github.projectmapk.jackson.module.kogera.jacksonObjectMapper
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+
+class ForProperty {
+    @JvmInline
+    value class Primitive(val v: Int)
+
+    @JvmInline
+    value class NonNullObject(val v: String)
+
+    @JvmInline
+    value class NullableObject(val v: String?)
+
+    data class Dto(
+        @get:JsonUnbox
+        val p0: Primitive = Primitive(0),
+        @get:JsonUnbox
+        val p1: Primitive? = Primitive(1),
+        @get:JsonUnbox
+        val p2: Primitive? = null,
+        @get:JsonUnbox
+        val nno0: NonNullObject = NonNullObject("0"),
+        @get:JsonUnbox
+        val nno1: NonNullObject? = NonNullObject("1"),
+        @get:JsonUnbox
+        val nno2: NonNullObject? = null,
+        @get:JsonUnbox
+        val no0: NullableObject = NullableObject("0"),
+        @get:JsonUnbox
+        val no1: NullableObject = NullableObject(null),
+        @get:JsonUnbox
+        val no2: NullableObject? = NullableObject("2"),
+        @get:JsonUnbox
+        val no3: NullableObject? = null
+    )
+
+    @Test
+    fun test() {
+        val expected =
+            """{"p0":0,"p1":1,"p2":null,"nno0":"0","nno1":"1","nno2":null,"no0":"0","no1":null,"no2":"2","no3":null}"""
+        val actual = jacksonObjectMapper().writeValueAsString(Dto())
+
+        assertEquals(expected, actual)
+    }
+}