Package kotlinx.serialization
Basic core concepts and annotations that set up serialization process.
Basic core concepts and annotations that set up serialization process.
Types
SerialFormat that allows conversions to and from ByteArray via encodeToByteArray and decodeFromByteArray methods.
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.
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.
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.
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.
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.
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.
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.
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
Instructs the serialization plugin to use PolymorphicSerializer on an annotated property or type usage. When used on class, replaces its serializer with PolymorphicSerializer everywhere.
This class provides support for multiplatform polymorphic serialization of sealed classes.
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.
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.
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.
A generic exception indicating the problem in serialization or deserialization process. This is a generic exception type that can be thrown during the problem at any stage of the serialization, including encoding, decoding, serialization, deserialization. SerialFormat implementors should throw subclasses of this exception at any unexpected event, whether it is a malformed input or unsupported class layout.
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.
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.
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.
SerialFormat that allows conversions to and from String via encodeToString and decodeFromString methods.
Marks this property invisible for the whole serialization process, including serial descriptors. Transient properties should have default values.
Instructs the plugin to use ContextualSerializer for every type in the current file that is listed in the forClasses.
Adds serializerClasses to serializers resolving process inside the plugin. Each of serializerClasses must implement KSerializer.
Functions
Decodes and deserializes the given byte array to the value of type T using deserializer retrieved from the reified type parameter.
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.
Serializes and encodes the given value to byte array using serializer retrieved from the reified type parameter.
Serializes and encodes the given value to byte array, delegating it to the BinaryFormat, and then encodes resulting bytes to hex string.
Serializes and encodes the given value to string using serializer retrieved from the reified type parameter.
Retrieves a serializer for the given type T. This method is a reified version of serializer(KType).
Retrieves a KSerializer for the given KClass. The given class must be annotated with Serializable or be one of the built-in types.
Retrieves serializer for the given type T from the current SerializersModule and, if not found, fallbacks to plain serializer method.
Creates a serializer for the given type. type argument can be obtained with experimental typeOf method.
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.
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.
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.
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).
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).
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.