Add guide for delegating serializers and wrapping serial descriptor (Kotlin#1591)

Fixes Kotlin#1588

Co-authored-by: Vsevolod Tolstopyatov <[email protected]>
Co-authored-by: Paul de Vrieze <[email protected]>

Author: 3 people

docs/formats.md

@@ -1098,7 +1098,7 @@ In the encoder this is achieved by overriding the
 In our `DataOutput` format example we might want to provide a specialized efficient data path for serializing an array
 of bytes since [DataOutput][java.io.DataOutput] has a special method for this purpose.
 
-Detection of the type is performed by looking at the `serializer`, not by checking the type of the `value`
+Detection of the type is performed by looking at the `serializer.descriptor`, not by checking the type of the `value`
 being serialized, so we fetch the builtin [KSerializer] instance for `ByteArray` type.
 
 > This an important difference. This way our format implementation properly supports 
@@ -1151,7 +1151,7 @@ class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
 
 ```kotlin
     override fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) {
-        if (serializer === byteArraySerializer)
+        if (serializer.descriptor == byteArraySerializer.descriptor)
             encodeByteArray(value as ByteArray)
         else
             super.encodeSerializableValue(serializer, value)
@@ -1218,7 +1218,7 @@ the [decodeSerializableValue][Decoder.decodeSerializableValue] function.
 ```kotlin 
     @Suppress("UNCHECKED_CAST")
     override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T =
-        if (deserializer === byteArraySerializer)
+        if (deserializer.descriptor == byteArraySerializer.descriptor)
             decodeByteArray() as T
         else
             super.decodeSerializableValue(deserializer, previousValue)

docs/serialization-guide.md

@@ -62,6 +62,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='using-top-level-serializer-function'></a>[Using top-level serializer function](serializers.md#using-top-level-serializer-function)
 * <a name='custom-serializers'></a>[Custom serializers](serializers.md#custom-serializers)
   * <a name='primitive-serializer'></a>[Primitive serializer](serializers.md#primitive-serializer)
+  * <a name='delegating-serializers'></a>[Delegating serializers](serializers.md#delegating-serializers)
   * <a name='composite-serializer-via-surrogate'></a>[Composite serializer via surrogate](serializers.md#composite-serializer-via-surrogate)
   * <a name='hand-written-composite-serializer'></a>[Hand-written composite serializer](serializers.md#hand-written-composite-serializer)
   * <a name='sequential-decoding-protocol-experimental'></a>[Sequential decoding protocol (experimental)](serializers.md#sequential-decoding-protocol-experimental)

docs/serializers.md

@@ -17,6 +17,7 @@ In this chapter we'll take a look at serializers in more detail, and we'll see h
   * [Using top-level serializer function](#using-top-level-serializer-function)
 * [Custom serializers](#custom-serializers)
   * [Primitive serializer](#primitive-serializer)
+  * [Delegating serializers](#delegating-serializers)
   * [Composite serializer via surrogate](#composite-serializer-via-surrogate)
   * [Hand-written composite serializer](#hand-written-composite-serializer)
   * [Sequential decoding protocol (experimental)](#sequential-decoding-protocol-experimental)
@@ -377,6 +378,72 @@ Both `Color` properties are serialized as strings.
 
 <!--- TEST -->
 
+### Delegating serializers
+
+In the previous example, we represented the `Color` class as a string.
+String is considered to be a primitive type, therefore we used `PrimitiveClassDescriptor` and specialized `encodeString` method. 
+Now let's see what our actions would be if we have to serialize `Color` as another non-primitive type, let's say `IntArray`.
+
+An implementation of [KSerializer] for our original `Color` class is going to perform a conversion between
+`Color` and `IntArray`, but delegate the actual serialization logic to the `IntArraySerializer`
+using [encodeSerializableValue][Encoder.encodeSerializableValue] and
+[decodeSerializableValue][Decoder.decodeSerializableValue].
+
+```kotlin
+import kotlinx.serialization.builtins.IntArraySerializer
+
+class ColorIntArraySerializer : KSerializer<Color> {
+    private val delegateSerializer = IntArraySerializer()
+    override val descriptor = SerialDescriptor("Color", delegateSerializer.descriptor)
+
+    override fun serialize(encoder: Encoder, value: Color) {
+        val data = intArrayOf(
+            (value.rgb shr 16) and 0xFF,
+            (value.rgb shr 8) and 0xFF,
+            value.rgb and 0xFF
+        )
+        encoder.encodeSerializableValue(delegateSerializer, data)
+    }
+
+    override fun deserialize(decoder: Decoder): Color {
+        val array = decoder.decodeSerializableValue(delegateSerializer)
+        return Color((array[0] shl 16) or (array[1] shl 8) or array[2])
+    }
+}
+```
+
+Note that we can't use default `Color.serializer().descriptor` here because formats that rely
+on the schema may think that we would call `encodeInt` instead of `encodeSerializableValue`.
+Neither we can use `IntArraySerializer().descriptor` directly — otherwise, formats that handle int arrays specially
+can't tell if `value` is really a `IntArray` or a `Color`. Don't worry, this optimization would still kick in
+when serializing actual underlying int array.
+
+> Example of how format can treat arrays specially is shown in the [formats guide](formats.md#format-specific-types).
+
+Now we can use the serializer:
+
+```kotlin
+@Serializable(with = ColorIntArraySerializer::class)
+class Color(val rgb: Int)
+
+fun main() {
+    val green = Color(0x00ff00)
+    println(Json.encodeToString(green))
+}  
+```    
+
+As you can see, such array representation is not very useful in JSON,
+but may save some space when used with a `ByteArray` and a binary format.
+
+> You can get the full code [here](../guide/example/example-serializer-10.kt).
+
+```text
+[0,255,0]
+```
+
+<!--- TEST -->
+
+
 ### Composite serializer via surrogate
 
 Now our challenge is to get `Color` serialized so that it is represented in JSON as if it is a class 
@@ -403,11 +470,9 @@ private class ColorSurrogate(val r: Int, val g: Int, val b: Int) {
 Now we can use the `ColorSurrogate.serializer()` function to retrieve a plugin-generated serializer for the
 surrogate class.
 
-An implementation of [KSerializer] for our original `Color` class is going to perform a conversion between
-`Color` and `ColorSurrogate`, but delegate the actual serialization logic to the `ColorSurrogate.serializer()`
-using [encodeSerializableValue][Encoder.encodeSerializableValue] and
-[decodeSerializableValue][Decoder.decodeSerializableValue], fully reusing an automatically
-generated [SerialDescriptor] for the surrogate.
+We can use the same approach as in [delegating serializer](#delegating-serializers), but this time,
+we are fully reusing an automatically
+generated [SerialDescriptor] for the surrogate because it should be indistinguishable from the original.
 
 ```kotlin
 object ColorSerializer : KSerializer<Color> {
@@ -441,7 +506,7 @@ fun main() {
 }
 -->
 
-> You can get the full code [here](../guide/example/example-serializer-10.kt).
+> You can get the full code [here](../guide/example/example-serializer-11.kt).
 
 ```text
 {"r":0,"g":255,"b":0}
@@ -535,7 +600,7 @@ fun main() {
 }  
 ```              
 
-> You can get the full code [here](../guide/example/example-serializer-11.kt).
+> You can get the full code [here](../guide/example/example-serializer-12.kt).
 
 As before, we got the `Color` class represented as a JSON object with three keys:
 
@@ -609,7 +674,7 @@ fun main() {
 }  
 -->
 
-> You can get the full code [here](../guide/example/example-serializer-12.kt).
+> You can get the full code [here](../guide/example/example-serializer-13.kt).
 
 <!--- TEST
 {"r":0,"g":255,"b":0}
@@ -656,7 +721,7 @@ fun main() {
 }
 ``` 
 
-> You can get the full code [here](../guide/example/example-serializer-13.kt).
+> You can get the full code [here](../guide/example/example-serializer-14.kt).
 
 ```text
 1455494400000
@@ -694,7 +759,7 @@ fun main() {
 }
 ``` 
 
-> You can get the full code [here](../guide/example/example-serializer-14.kt).
+> You can get the full code [here](../guide/example/example-serializer-15.kt).
 
 The `stableReleaseDate` property is serialized with the serialization strategy that we specified for it:
 
@@ -737,7 +802,7 @@ fun main() {
     println(Json.encodeToString(data))
 }
 ```   
-> You can get the full code [here](../guide/example/example-serializer-15.kt).
+> You can get the full code [here](../guide/example/example-serializer-16.kt).
 
 ```text
 {"name":"Kotlin","stableReleaseDate":1455494400000}
@@ -785,7 +850,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-serializer-16.kt).
+> You can get the full code [here](../guide/example/example-serializer-17.kt).
 
 The resulting JSON looks like the `Project` class was serialized directly.
 
@@ -849,7 +914,7 @@ fun main() {
 To actually serialize this class we must provide the corresponding context when calling the `encodeToXxx`/`decodeFromXxx`
 functions. Without it we'll get a "Serializer for class 'Date' is not found" exception.
 
-> See [here](../guide/example/example-serializer-17.kt) for an example that produces that exception.
+> See [here](../guide/example/example-serializer-18.kt) for an example that produces that exception.
 
 <!--- TEST LINES_START 
 Exception in thread "main" kotlinx.serialization.SerializationException: Serializer for class 'Date' is not found.
@@ -908,7 +973,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-serializer-18.kt).
+> You can get the full code [here](../guide/example/example-serializer-19.kt).
 ```text
 {"name":"Kotlin","stableReleaseDate":1455494400000}
 ```
@@ -967,7 +1032,7 @@ fun main() {
 }
 ```          
 
-> You can get the full code [here](../guide/example/example-serializer-19.kt).
+> You can get the full code [here](../guide/example/example-serializer-20.kt).
 
 This gets all the `Project` properties serialized:
 
@@ -1008,7 +1073,7 @@ fun main() {
 }
 ```             
 
-> You can get the full code [here](../guide/example/example-serializer-20.kt).
+> You can get the full code [here](../guide/example/example-serializer-21.kt).
 
 The output is shown below.
 

guide/example/example-formats-15.kt

@@ -31,7 +31,7 @@ class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
     override fun encodeNotNullMark() = encodeBoolean(true)
 
     override fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) {
-        if (serializer === byteArraySerializer)
+        if (serializer.descriptor == byteArraySerializer.descriptor)
             encodeByteArray(value as ByteArray)
         else
             super.encodeSerializableValue(serializer, value)
@@ -90,7 +90,7 @@ class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : Abstr
 
     @Suppress("UNCHECKED_CAST")
     override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T =
-        if (deserializer === byteArraySerializer)
+        if (deserializer.descriptor == byteArraySerializer.descriptor)
             decodeByteArray() as T
         else
             super.decodeSerializableValue(deserializer, previousValue)

guide/example/example-serializer-10.kt

@@ -6,31 +6,31 @@ import kotlinx.serialization.json.*
 import kotlinx.serialization.encoding.*
 import kotlinx.serialization.descriptors.*
 
-@Serializable
-@SerialName("Color")
-private class ColorSurrogate(val r: Int, val g: Int, val b: Int) {
-    init {     
-        require(r in 0..255 && g in 0..255 && b in 0..255)
-    }
-}
+import kotlinx.serialization.builtins.IntArraySerializer
 
-object ColorSerializer : KSerializer<Color> {
-    override val descriptor: SerialDescriptor = ColorSurrogate.serializer().descriptor
+class ColorIntArraySerializer : KSerializer<Color> {
+    private val delegateSerializer = IntArraySerializer()
+    override val descriptor = SerialDescriptor("Color", delegateSerializer.descriptor)
 
     override fun serialize(encoder: Encoder, value: Color) {
-        val surrogate = ColorSurrogate((value.rgb shr 16) and 0xff, (value.rgb shr 8) and 0xff, value.rgb and 0xff)
-        encoder.encodeSerializableValue(ColorSurrogate.serializer(), surrogate)
+        val data = intArrayOf(
+            (value.rgb shr 16) and 0xFF,
+            (value.rgb shr 8) and 0xFF,
+            value.rgb and 0xFF
+        )
+        encoder.encodeSerializableValue(delegateSerializer, data)
     }
 
     override fun deserialize(decoder: Decoder): Color {
-        val surrogate = decoder.decodeSerializableValue(ColorSurrogate.serializer())
-        return Color((surrogate.r shl 16) or (surrogate.g shl 8) or surrogate.b)
+        val array = decoder.decodeSerializableValue(delegateSerializer)
+        return Color((array[0] shl 16) or (array[1] shl 8) or array[2])
     }
 }
 
-@Serializable(with = ColorSerializer::class)
+@Serializable(with = ColorIntArraySerializer::class)
 class Color(val rgb: Int)
+
 fun main() {
     val green = Color(0x00ff00)
     println(Json.encodeToString(green))
-}
+}  

guide/example/example-serializer-11.kt

@@ -6,47 +6,31 @@ import kotlinx.serialization.json.*
 import kotlinx.serialization.encoding.*
 import kotlinx.serialization.descriptors.*
 
-object ColorAsObjectSerializer : KSerializer<Color> {
+@Serializable
+@SerialName("Color")
+private class ColorSurrogate(val r: Int, val g: Int, val b: Int) {
+    init {     
+        require(r in 0..255 && g in 0..255 && b in 0..255)
+    }
+}
 
-    override val descriptor: SerialDescriptor =
-        buildClassSerialDescriptor("Color") {
-            element<Int>("r")
-            element<Int>("g")
-            element<Int>("b")
-        }
+object ColorSerializer : KSerializer<Color> {
+    override val descriptor: SerialDescriptor = ColorSurrogate.serializer().descriptor
 
-    override fun serialize(encoder: Encoder, value: Color) =
-        encoder.encodeStructure(descriptor) {
-            encodeIntElement(descriptor, 0, (value.rgb shr 16) and 0xff)
-            encodeIntElement(descriptor, 1, (value.rgb shr 8) and 0xff)
-            encodeIntElement(descriptor, 2, value.rgb and 0xff)
-        }
+    override fun serialize(encoder: Encoder, value: Color) {
+        val surrogate = ColorSurrogate((value.rgb shr 16) and 0xff, (value.rgb shr 8) and 0xff, value.rgb and 0xff)
+        encoder.encodeSerializableValue(ColorSurrogate.serializer(), surrogate)
+    }
 
-    override fun deserialize(decoder: Decoder): Color =
-        decoder.decodeStructure(descriptor) {
-            var r = -1
-            var g = -1
-            var b = -1
-            while (true) {
-                when (val index = decodeElementIndex(descriptor)) {
-                    0 -> r = decodeIntElement(descriptor, 0)
-                    1 -> g = decodeIntElement(descriptor, 1)
-                    2 -> b = decodeIntElement(descriptor, 2)
-                    CompositeDecoder.DECODE_DONE -> break
-                    else -> error("Unexpected index: $index")
-                }
-            }
-            require(r in 0..255 && g in 0..255 && b in 0..255)
-            Color((r shl 16) or (g shl 8) or b)
-        }
+    override fun deserialize(decoder: Decoder): Color {
+        val surrogate = decoder.decodeSerializableValue(ColorSurrogate.serializer())
+        return Color((surrogate.r shl 16) or (surrogate.g shl 8) or surrogate.b)
+    }
 }
 
-@Serializable(with = ColorAsObjectSerializer::class)
-data class Color(val rgb: Int)
-
+@Serializable(with = ColorSerializer::class)
+class Color(val rgb: Int)
 fun main() {
-    val color = Color(0x00ff00)
-    val string = Json.encodeToString(color) 
-    println(string)
-    require(Json.decodeFromString<Color>(string) == color)
-}  
+    val green = Color(0x00ff00)
+    println(Json.encodeToString(green))
+}

guide/example/example-serializer-12.kt

@@ -26,12 +26,8 @@ object ColorAsObjectSerializer : KSerializer<Color> {
         decoder.decodeStructure(descriptor) {
             var r = -1
             var g = -1
-            var b = -1     
-            if (decodeSequentially()) { // sequential decoding protocol
-                r = decodeIntElement(descriptor, 0)           
-                g = decodeIntElement(descriptor, 1)  
-                b = decodeIntElement(descriptor, 2)
-            } else while (true) {
+            var b = -1
+            while (true) {
                 when (val index = decodeElementIndex(descriptor)) {
                     0 -> r = decodeIntElement(descriptor, 0)
                     1 -> g = decodeIntElement(descriptor, 1)
@@ -43,7 +39,7 @@ object ColorAsObjectSerializer : KSerializer<Color> {
             require(r in 0..255 && g in 0..255 && b in 0..255)
             Color((r shl 16) or (g shl 8) or b)
         }
-}        
+}
 
 @Serializable(with = ColorAsObjectSerializer::class)
 data class Color(val rgb: Int)