1 /*
2  * Copyright 2017-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
3  */
4 
5 @file:Suppress("RedundantVisibilityModifier")
6 
7 package kotlinx.serialization.modules
8 
9 import kotlinx.serialization.*
10 import kotlin.reflect.*
11 
12 /**
13  * [SerializersModuleCollector] can introspect and accumulate content of any [SerializersModule] via [SerializersModule.dumpTo],
14  * using a visitor-like pattern: [contextual] and [polymorphic] functions are invoked for each registered serializer.
15  *
16  * ### Not stable for inheritance
17  *
18  * `SerializersModuleCollector` interface is not stable for inheritance in 3rd party libraries, as new methods
19  * might be added to this interface or contracts of the existing methods can be changed.
20  */
21 @ExperimentalSerializationApi
22 public interface SerializersModuleCollector {
23 
24     /**
25      * Accept a serializer, associated with [kClass] for contextual serialization.
26      */
contextualnull27     public fun <T : Any> contextual(kClass: KClass<T>, serializer: KSerializer<T>): Unit =
28         contextual(kClass) { serializer }
29 
30 
31     /**
32      * Accept a provider, associated with generic [kClass] for contextual serialization.
33      */
contextualnull34     public fun <T : Any> contextual(
35         kClass: KClass<T>,
36         provider: (typeArgumentsSerializers: List<KSerializer<*>>) -> KSerializer<*>
37     )
38 
39     /**
40      * Accept a serializer, associated with [actualClass] for polymorphic serialization.
41      */
42     public fun <Base : Any, Sub : Base> polymorphic(
43         baseClass: KClass<Base>,
44         actualClass: KClass<Sub>,
45         actualSerializer: KSerializer<Sub>
46     )
47 
48     /**
49      * Accept a default serializer provider, associated with the [baseClass] for polymorphic serialization.
50      * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` in the scope of [baseClass] were found.
51      *
52      * Default serializers provider affects only serialization process. Deserializers are accepted in the
53      * [SerializersModuleCollector.polymorphicDefaultDeserializer] method.
54      *
55      * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
56      */
57     public fun <Base : Any> polymorphicDefaultSerializer(
58         baseClass: KClass<Base>,
59         defaultSerializerProvider: (value: Base) -> SerializationStrategy<Base>?
60     )
61 
62     /**
63      * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization.
64      * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
65      * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators
66      * (currently only `Json` with `useArrayPolymorphism` set to `false`).
67      *
68      * Default deserializers provider affects only deserialization process. Serializers are accepted in the
69      * [SerializersModuleCollector.polymorphicDefaultSerializer] method.
70      *
71      * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
72      */
73     public fun <Base : Any> polymorphicDefaultDeserializer(
74         baseClass: KClass<Base>,
75         defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
76     )
77 
78     /**
79      * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization.
80      *
81      * This function affect only deserialization process. To avoid confusion, it was deprecated and replaced with [polymorphicDefaultDeserializer].
82      * To affect serialization process, use [SerializersModuleCollector.polymorphicDefaultSerializer].
83      *
84      * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
85      * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators
86      * (currently only `Json` with `useArrayPolymorphism` set to `false`).
87      *
88      * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
89      *
90      * @see SerializersModuleCollector.polymorphicDefaultDeserializer
91      * @see SerializersModuleCollector.polymorphicDefaultSerializer
92      */
93     @Deprecated(
94         "Deprecated in favor of function with more precise name: polymorphicDefaultDeserializer",
95         ReplaceWith("polymorphicDefaultDeserializer(baseClass, defaultDeserializerProvider)"),
96         DeprecationLevel.WARNING // Since 1.5.0. Raise to ERROR in 1.6.0, hide in 1.7.0
97     )
98     public fun <Base : Any> polymorphicDefault(
99         baseClass: KClass<Base>,
100         defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
101     ) {
102         polymorphicDefaultDeserializer(baseClass, defaultDeserializerProvider)
103     }
104 }
105