Skip to content

Commit

Permalink
Deprecate SerializersModuleCollector.polymorphicDefault and Polymorph…
Browse files Browse the repository at this point in the history
…icModuleBuilder.default

Replaced with default polymorphicDefaultDeserializer and defaultDeserializer respectively.
Remove experimentality from SerializersModuleCollector.polymorphicDefaultSerializer.

This is a follow-up for #1686 — finishing migration path
  • Loading branch information
sandwwraith committed Oct 24, 2022
1 parent 46a5ff6 commit 67270d7
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 33 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,19 @@ public class PolymorphicModuleBuilder<in Base : Any> @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<out Base>?) {
require(this.defaultDeserializerProvider == null) {
"Default deserializer provider is already registered for class $baseClass: ${this.defaultDeserializerProvider}"
Expand All @@ -55,26 +56,23 @@ public class PolymorphicModuleBuilder<in Base : Any> @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)"))
public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy<out Base>?) {
defaultDeserializer(defaultSerializerProvider)
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Base : Any> polymorphicDefaultSerializer(
baseClass: KClass<Base>,
defaultSerializerProvider: (value: Base) -> SerializationStrategy<Base>?
Expand All @@ -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 <Base : Any> polymorphicDefaultDeserializer(
baseClass: KClass<Base>,
defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,27 +47,29 @@ 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 <Base : Any> polymorphicDefaultSerializer(
baseClass: KClass<Base>,
defaultSerializerProvider: (value: Base) -> SerializationStrategy<Base>?
)

/**
* 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 <Base : Any> polymorphicDefaultDeserializer(
baseClass: KClass<Base>,
defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
Expand All @@ -76,12 +78,22 @@ 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)")
)
public fun <Base : Any> polymorphicDefault(
baseClass: KClass<Base>,
defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
Expand Down

0 comments on commit 67270d7

Please sign in to comment.