From b581abe182f40d4e822ae508778910e9c8b506f1 Mon Sep 17 00:00:00 2001 From: Leonid Startsev Date: Thu, 27 Oct 2022 18:27:34 +0300 Subject: [PATCH] Deprecate SerializersModuleCollector.polymorphicDefault and PolymorphicModuleBuilder.default (#2076) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaced with default polymorphicDefaultDeserializer and defaultDeserializer respectively. Remove experimentality from SerializersModuleCollector.polymorphicDefaultSerializer. This is a follow-up for https://github.com/Kotlin/kotlinx.serialization/pull/1686 — finishing migration path --- .../modules/PolymorphicModuleBuilder.kt | 32 ++++++++-------- .../modules/SerializersModuleBuilders.kt | 16 +++++--- .../modules/SerializersModuleCollector.kt | 37 +++++++++++++------ 3 files changed, 52 insertions(+), 33 deletions(-) diff --git a/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt b/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt index a9b6312e09..1b8d431e1a 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt +++ b/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt @@ -34,18 +34,19 @@ public class PolymorphicModuleBuilder @PublishedApi internal cons * Adds a default serializers provider associated with the given [baseClass] to the resulting module. * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className` * were found. `className` could be `null` for formats that support nullable class discriminators - * (currently only [Json] with [useArrayPolymorphism][JsonBuilder.useArrayPolymorphism] set to `false`) + * (currently only `Json` with `JsonBuilder.useArrayPolymorphism` set to `false`) + * + * Default deserializers provider affects only deserialization process. To affect serialization process, use + * [SerializersModuleBuilder.polymorphicDefaultSerializer]. * * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically. * * Typically, if the class is not registered in advance, it is not possible to know the structure of the unknown * type and have a precise serializer, so the default serializer has limited capabilities. - * To have a structural access to the unknown data, it is recommended to use [JsonTransformingSerializer] - * or [JsonContentPolymorphicSerializer] classes. + * If you're using `Json` format, you can get a structural access to the unknown data using `JsonContentPolymorphicSerializer`. * - * Default deserializers provider affects only deserialization process. + * @see SerializersModuleBuilder.polymorphicDefaultSerializer */ - @ExperimentalSerializationApi public fun defaultDeserializer(defaultDeserializerProvider: (className: String?) -> DeserializationStrategy?) { require(this.defaultDeserializerProvider == null) { "Default deserializer provider is already registered for class $baseClass: ${this.defaultDeserializerProvider}" @@ -55,26 +56,27 @@ public class PolymorphicModuleBuilder @PublishedApi internal cons /** * Adds a default deserializers provider associated with the given [baseClass] to the resulting module. + * This function affect only deserialization process. To avoid confusion, it was deprecated and replaced with [defaultDeserializer]. + * To affect serialization process, use [SerializersModuleBuilder.polymorphicDefaultSerializer]. + * * [defaultSerializerProvider] is invoked when no polymorphic serializers associated with the `className` * were found. `className` could be `null` for formats that support nullable class discriminators - * (currently only [Json] with [useArrayPolymorphism][JsonBuilder.useArrayPolymorphism] set to `false`) + * (currently only `Json` with `JsonBuilder.useArrayPolymorphism` set to `false`) * * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically. * - * [defaultSerializerProvider] is named as such for backwards compatibility reasons; it provides deserializers. - * * Typically, if the class is not registered in advance, it is not possible to know the structure of the unknown * type and have a precise serializer, so the default serializer has limited capabilities. - * To have a structural access to the unknown data, it is recommended to use [JsonTransformingSerializer] - * or [JsonContentPolymorphicSerializer] classes. - * - * Default deserializers provider affects only deserialization process. To affect serialization process, use - * [SerializersModuleBuilder.polymorphicDefaultSerializer]. + * If you're using `Json` format, you can get a structural access to the unknown data using `JsonContentPolymorphicSerializer`. * * @see defaultDeserializer + * @see SerializersModuleBuilder.polymorphicDefaultSerializer */ - @OptIn(ExperimentalSerializationApi::class) - // TODO: deprecate in 1.4 + @Deprecated( + "Deprecated in favor of function with more precise name: defaultDeserializer", + ReplaceWith("defaultDeserializer(defaultSerializerProvider)"), + DeprecationLevel.WARNING // Since 1.5.0. Raise to ERROR in 1.6.0, hide in 1.7.0 + ) public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy?) { defaultDeserializer(defaultSerializerProvider) } diff --git a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt index c4d83aeceb..26c93769e8 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt +++ b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt @@ -97,11 +97,13 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser /** * Adds a default serializers provider associated with the given [baseClass] to the resulting module. - * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` were found. + * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` in the scope of [baseClass] were found. * - * This will not affect deserialization. + * Default serializers provider affects only serialization process. To affect deserialization process, use + * [SerializersModuleBuilder.polymorphicDefaultDeserializer]. + * + * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically. */ - @ExperimentalSerializationApi public override fun polymorphicDefaultSerializer( baseClass: KClass, defaultSerializerProvider: (value: Base) -> SerializationStrategy? @@ -112,14 +114,16 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser /** * Adds a default deserializers provider associated with the given [baseClass] to the resulting module. * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className` - * were found. `className` could be `null` for formats that support nullable class discriminators + * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators * (currently only `Json` with `useArrayPolymorphism` set to `false`). * - * This will not affect serialization. + * Default deserializers provider affects only deserialization process. To affect serialization process, use + * [SerializersModuleBuilder.polymorphicDefaultSerializer]. + * + * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically. * * @see PolymorphicModuleBuilder.defaultDeserializer */ - @ExperimentalSerializationApi public override fun polymorphicDefaultDeserializer( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy? diff --git a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt index 87ddd81d79..c33d45a4c2 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt +++ b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt @@ -47,13 +47,13 @@ public interface SerializersModuleCollector { /** * Accept a default serializer provider, associated with the [baseClass] for polymorphic serialization. + * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` in the scope of [baseClass] were found. * - * This will not affect deserialization. + * Default serializers provider affects only serialization process. Deserializers are accepted in the + * [SerializersModuleCollector.polymorphicDefaultDeserializer] method. * - * @see SerializersModuleBuilder.polymorphicDefaultSerializer - * @see PolymorphicModuleBuilder.defaultSerializer + * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically. */ - @ExperimentalSerializationApi public fun polymorphicDefaultSerializer( baseClass: KClass, defaultSerializerProvider: (value: Base) -> SerializationStrategy? @@ -61,13 +61,15 @@ public interface SerializersModuleCollector { /** * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization. + * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className` + * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators + * (currently only `Json` with `useArrayPolymorphism` set to `false`). * - * This will not affect serialization. + * Default deserializers provider affects only deserialization process. Serializers are accepted in the + * [SerializersModuleCollector.polymorphicDefaultSerializer] method. * - * @see SerializersModuleBuilder.polymorphicDefaultDeserializer - * @see PolymorphicModuleBuilder.defaultDeserializer + * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically. */ - @ExperimentalSerializationApi public fun polymorphicDefaultDeserializer( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy? @@ -76,12 +78,23 @@ public interface SerializersModuleCollector { /** * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization. * - * This will not affect serialization. + * This function affect only deserialization process. To avoid confusion, it was deprecated and replaced with [polymorphicDefaultDeserializer]. + * To affect serialization process, use [SerializersModuleCollector.polymorphicDefaultSerializer]. * - * @see SerializersModuleBuilder.polymorphicDefaultDeserializer - * @see PolymorphicModuleBuilder.defaultDeserializer + * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className` + * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators + * (currently only `Json` with `useArrayPolymorphism` set to `false`). + * + * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically. + * + * @see SerializersModuleCollector.polymorphicDefaultDeserializer + * @see SerializersModuleCollector.polymorphicDefaultSerializer */ - // TODO: deprecate in 1.4 + @Deprecated( + "Deprecated in favor of function with more precise name: polymorphicDefaultDeserializer", + ReplaceWith("polymorphicDefaultDeserializer(baseClass, defaultDeserializerProvider)"), + DeprecationLevel.WARNING // Since 1.5.0. Raise to ERROR in 1.6.0, hide in 1.7.0 + ) public fun polymorphicDefault( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy?