Package kotlinx.serialization

Basic core concepts and annotations that set up serialization process.

Basic core concepts and annotations that set up serialization process.

Types

Link copied to clipboard
interface BinaryFormat : SerialFormat

SerialFormat that allows conversions to and from ByteArray via encodeToByteArray and decodeFromByteArray methods.

Link copied to clipboard
annotation class Contextual

Instructs the plugin to use ContextualSerializer on a given property or type. Context serializer is usually used when serializer for type can only be found in runtime. It is also possible to apply ContextualSerializer to every property of the given type, using file-level UseContextualSerialization annotation.

Link copied to clipboard
class ContextualSerializer<T : Any>(    serializableClass: KClass<T>,     fallbackSerializer: KSerializer<T>?,     typeArgumentsSerializers: Array<KSerializer<*>>) : KSerializer<T>

This class provides support for retrieving a serializer in runtime, instead of using the one precompiled by the serialization plugin. This serializer is enabled by Contextual or UseContextualSerialization.

Link copied to clipboard
interface DeserializationStrategy<T>

Deserialization strategy defines the serial form of a type T, including its structural description, declared by the descriptor and the actual deserialization process, defined by the implementation of the deserialize method.

Link copied to clipboard
annotation class EncodeDefault(val mode: EncodeDefault.Mode = Mode.ALWAYS)

Controls whether the target property is serialized when its value is equal to a default value, regardless of the format settings. Does not affect decoding and deserialization process.

Link copied to clipboard

Marks declarations that are still experimental in kotlinx.serialization, which means that the design of the corresponding declarations has open issues which may (or may not) lead to their changes in the future. Roughly speaking, there is a chance that those declarations will be deprecated in the near future or the semantics of their behavior may change in some way that may break some code.

Link copied to clipboard
annotation class InheritableSerialInfo

Meta-annotation that commands the compiler plugin to handle the annotation as serialization-specific. Serialization-specific annotations are preserved in the SerialDescriptor and can be retrieved during serialization process with SerialDescriptor.getElementAnnotations.

Link copied to clipboard

Public API marked with this annotation is effectively internal, which means it should not be used outside of kotlinx.serialization. Signature, semantics, source and binary compatibilities are not guaranteed for this API and will be changed without any warnings or migration aids. If you cannot avoid using internal API to solve your problem, please report your use-case to serialization's issue tracker.

Link copied to clipboard
interface KSerializer<T> : SerializationStrategy<T> , DeserializationStrategy<T>

KSerializer is responsible for the representation of a serial form of a type T in terms of encoders and decoders and for constructing and deconstructing T from/to a sequence of encoding primitives. For classes marked with @Serializable, can be obtained from generated companion extension .serializer() or from serializer() function.

Link copied to clipboard
annotation class MetaSerializable

The meta-annotation for adding Serializable behaviour to user-defined annotations.

Link copied to clipboard
class MissingFieldException(    missingFields: List<String>,     message: String?,     cause: Throwable?) : SerializationException

Thrown when KSerializer did not receive a non-optional property from CompositeDecoder and CompositeDecoder.decodeElementIndex had already returned CompositeDecoder.DECODE_DONE.

Link copied to clipboard
annotation class Polymorphic

Instructs the serialization plugin to use PolymorphicSerializer on an annotated property or type usage. When used on class, replaces its serializer with PolymorphicSerializer everywhere.

Link copied to clipboard
class PolymorphicSerializer<T : Any>(val baseClass: KClass<T>) : AbstractPolymorphicSerializer<T>

This class provides support for multiplatform polymorphic serialization for interfaces and abstract classes.

Link copied to clipboard
@Target(allowedTargets = [AnnotationTarget.PROPERTY])
annotation class Required

Indicates that property must be present during deserialization process, despite having a default value.

Link copied to clipboard
class SealedClassSerializer<T : Any>(    serialName: String,     val baseClass: KClass<T>,     subclasses: Array<KClass<out T>>,     subclassSerializers: Array<KSerializer<out T>>) : AbstractPolymorphicSerializer<T>

This class provides support for multiplatform polymorphic serialization of sealed classes.

Link copied to clipboard
interface SerialFormat

Represents an instance of a serialization format that can interact with KSerializer and is a supertype of all entry points for a serialization. It does not impose any restrictions on a serialized form or underlying storage, neither it exposes them.

Link copied to clipboard
annotation class SerialInfo

Meta-annotation that commands the compiler plugin to handle the annotation as serialization-specific. Serialization-specific annotations are preserved in the SerialDescriptor and can be retrieved during serialization process with SerialDescriptor.getElementAnnotations for properties annotations and SerialDescriptor.annotations for class annotations.

Link copied to clipboard
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)

The main entry point to the serialization process. Applying Serializable to the Kotlin class instructs the serialization plugin to automatically generate implementation of KSerializer for the current class, that can be used to serialize and deserialize the class. The generated serializer can be accessed with T.serializer() extension function on the class companion, both are generated by the plugin as well.

Link copied to clipboard
open class SerializationException : IllegalArgumentException

A generic exception indicating the problem in serialization or deserialization process.

Link copied to clipboard
interface SerializationStrategy<in T>

Serialization strategy defines the serial form of a type T, including its structural description, declared by the descriptor and the actual serialization process, defined by the implementation of the serialize method.

Link copied to clipboard
annotation class Serializer(val forClass: KClass<*>)

Instructs the serialization plugin to turn this class into serializer for specified class forClass. However, it would not be used automatically. To apply it on particular class or property, use Serializable or UseSerializers, or Contextual with runtime registration.

Link copied to clipboard
annotation class SerialName(val value: String)

Overrides the name of a class or a property in the corresponding SerialDescriptor. Names and serial names are used by text-based serial formats in order to encode the name of the class or the name of the property, e.g. by Json.

Link copied to clipboard
interface StringFormat : SerialFormat

SerialFormat that allows conversions to and from String via encodeToString and decodeFromString methods.

Link copied to clipboard
@Target(allowedTargets = [AnnotationTarget.PROPERTY])
annotation class Transient

Marks this property invisible for the whole serialization process, including serial descriptors. Transient properties should have default values.

Link copied to clipboard
@Target(allowedTargets = [AnnotationTarget.FILE])
annotation class UseContextualSerialization(val forClasses: KClass<*>)

Instructs the plugin to use ContextualSerializer for every type in the current file that is listed in the forClasses.

Link copied to clipboard
@Target(allowedTargets = [AnnotationTarget.FILE])
annotation class UseSerializers(val serializerClasses: KClass<out KSerializer<*>>)

Adds serializerClasses to serializers resolving process inside the plugin. Each of serializerClasses must implement KSerializer.

Functions

Link copied to clipboard
inline fun <T> BinaryFormat.decodeFromByteArray(bytes: ByteArray): T

Decodes and deserializes the given byte array to the value of type T using deserializer retrieved from the reified type parameter.

Link copied to clipboard
inline fun <T> BinaryFormat.decodeFromHexString(hex: String): T
fun <T> BinaryFormat.decodeFromHexString(deserializer: DeserializationStrategy<T>, hex: String): T

Decodes byte array from the given hex string and the decodes and deserializes it to the value of type T, delegating it to the BinaryFormat.

Link copied to clipboard
inline fun <T> StringFormat.decodeFromString(string: String): T

Decodes and deserializes the given string to the value of type T using deserializer retrieved from the reified type parameter.

Link copied to clipboard
inline fun <T> BinaryFormat.encodeToByteArray(value: T): ByteArray

Serializes and encodes the given value to byte array using serializer retrieved from the reified type parameter.

Link copied to clipboard
inline fun <T> BinaryFormat.encodeToHexString(value: T): String
fun <T> BinaryFormat.encodeToHexString(serializer: SerializationStrategy<T>, value: T): String

Serializes and encodes the given value to byte array, delegating it to the BinaryFormat, and then encodes resulting bytes to hex string.

Link copied to clipboard
inline fun <T> StringFormat.encodeToString(value: T): String

Serializes and encodes the given value to string using serializer retrieved from the reified type parameter.

Link copied to clipboard
fun <T : Any> AbstractPolymorphicSerializer<T>.findPolymorphicSerializer(decoder: CompositeDecoder, klassName: String?): DeserializationStrategy<out T>
fun <T : Any> AbstractPolymorphicSerializer<T>.findPolymorphicSerializer(encoder: Encoder, value: T): SerializationStrategy<T>
Link copied to clipboard
inline fun <T> serializer(): KSerializer<T>

Retrieves a serializer for the given type T. This method is a reified version of serializer(KType).

fun <T : Any> KClass<T>.serializer(): KSerializer<T>

Retrieves a KSerializer for the given KClass. The given class must be annotated with Serializable or be one of the built-in types.

inline fun <T> SerializersModule.serializer(): KSerializer<T>

Retrieves serializer for the given type T from the current SerializersModule and, if not found, fallbacks to plain serializer method.

fun serializer(type: KType): KSerializer<Any?>

Creates a serializer for the given type. type argument can be obtained with experimental typeOf method.

fun SerializersModule.serializer(type: KType): KSerializer<Any?>

Attempts to create a serializer for the given type and fallbacks to contextual lookup for non-serializable types. type argument can be obtained with experimental typeOf method.

fun serializer(type: Type): KSerializer<Any>

Reflectively constructs a serializer for the given reflective Java type. serializer is intended to be used as an interoperability layer for libraries like GSON and Retrofit, that operate with reflective Java Type and cannot use typeOf.

Retrieves serializer for the given reflective Java type using reflective construction and contextual lookup for non-serializable types.

Link copied to clipboard
fun <T : Any> KClass<T>.serializerOrNull(): KSerializer<T>?

Retrieves a KSerializer for the given KClass or returns null if none is found. The given class must be annotated with Serializable or be one of the built-in types. This method uses platform-specific reflection available for the given erased KClass and it is not recommended to use this method for anything, but last-ditch resort, e.g. when all type info is lost, your application has crashed and it is the final attempt to log or send some serializable data.

fun serializerOrNull(type: KType): KSerializer<Any?>?

Creates a serializer for the given type. type argument can be obtained with experimental typeOf method. Returns null if serializer cannot be created (provided type or its type argument is not serializable).

fun SerializersModule.serializerOrNull(type: KType): KSerializer<Any?>?

Attempts to create a serializer for the given type and fallbacks to contextual lookup for non-serializable types. type argument can be obtained with experimental typeOf method. Returns null if serializer cannot be created (provided type or its type argument is not serializable and is not registered in this module).

fun serializerOrNull(type: Type): KSerializer<Any>?

Reflectively constructs a serializer for the given reflective Java type. serializer is intended to be used as an interoperability layer for libraries like GSON and Retrofit, that operate with reflective Java Type and cannot use typeOf.

Retrieves serializer for the given reflective Java type using reflective construction and contextual lookup for non-serializable types.