org.apache.flink.api.common.typeutils

Class TypeSerializer<T>

java.lang.Object

org.apache.flink.api.common.typeutils.TypeSerializer<T>

Type Parameters:

T - The data type that the serializer serializes.

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ArrayListSerializer, AvroSerializer, AvroSerializer, BackwardsCompatibleAvroSerializer, CopyableValueSerializer, EitherSerializer, EnumSerializer, GenericArraySerializer, InternalTimer.TimerSerializer, KryoSerializer, ListSerializer, MapSerializer, NFA.NFASerializer, PojoSerializer, RowSerializer, SharedBuffer.SharedBufferSerializer, StreamElementSerializer, TupleSerializerBase, TwoPhaseCommitSinkFunction.StateSerializer, TypeDeserializerAdapter, TypeSerializerSingleton, UnloadableDummyTypeSerializer, ValueSerializer, WritableSerializer

@PublicEvolving
public abstract class TypeSerializer<T>
extends Object
implements Serializable

This interface describes the methods that are required for a data type to be handled by the Flink runtime. Specifically, this interface contains the serialization and copying methods.

The methods in this class are assumed to be stateless, such that it is effectively thread safe. Stateful implementations of the methods may lead to unpredictable side effects and will compromise both stability and correctness of the program.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TypeSerializer()

Method Summary

Modifier and Type	Method and Description
abstract boolean	canEqual(Object obj) Returns true if the given object can be equaled with this object.
abstract void	copy(DataInputView source, DataOutputView target) Copies exactly one record from the source input view to the target output view.
abstract T	copy(T from) Creates a deep copy of the given element in a new element.
abstract T	copy(T from, T reuse) Creates a copy from the given element.
abstract T	createInstance() Creates a new instance of the data type.
abstract T	deserialize(DataInputView source) De-serializes a record from the given source input view.
abstract T	deserialize(T reuse, DataInputView source) De-serializes a record from the given source input view into the given reuse record instance if mutable.
abstract TypeSerializer<T>	duplicate() Creates a deep copy of this serializer if it is necessary, i.e.
abstract CompatibilityResult<T>	ensureCompatibility(TypeSerializerConfigSnapshot configSnapshot) Ensure compatibility of this serializer with a preceding serializer that was registered for serialization of the same managed state (if any - this method is only relevant if this serializer is registered for serialization of managed state).
abstract boolean	equals(Object obj)
abstract int	getLength() Gets the length of the data type, if it is a fix length data type.
abstract int	hashCode()
abstract boolean	isImmutableType() Gets whether the type is an immutable type.
abstract void	serialize(T record, DataOutputView target) Serializes the given record to the given target output view.
abstract TypeSerializerConfigSnapshot	snapshotConfiguration() Create a snapshot of the serializer's current configuration to be stored along with the managed state it is registered to (if any - this method is only relevant if this serializer is registered for serialization of managed state).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TypeSerializer

public TypeSerializer()

Method Detail

isImmutableType

public abstract boolean isImmutableType()

Gets whether the type is an immutable type.

Returns:

True, if the type is immutable.

duplicate

public abstract TypeSerializer<T> duplicate()

Creates a deep copy of this serializer if it is necessary, i.e. if it is stateful. This can return itself if the serializer is not stateful. We need this because Serializers might be used in several threads. Stateless serializers are inherently thread-safe while stateful serializers might not be thread-safe.

createInstance

public abstract T createInstance()

Creates a new instance of the data type.

Returns:

A new instance of the data type.

copy

public abstract T copy(T from)

Creates a deep copy of the given element in a new element.

Parameters:

from - The element reuse be copied.

Returns:

A deep copy of the element.

copy

public abstract T copy(T from,
                       T reuse)

Creates a copy from the given element. The method makes an attempt to store the copy in the given reuse element, if the type is mutable. This is, however, not guaranteed.

Parameters:

from - The element to be copied.

reuse - The element to be reused. May or may not be used.

Returns:

A deep copy of the element.

getLength

public abstract int getLength()

Gets the length of the data type, if it is a fix length data type.

Returns:

The length of the data type, or -1 for variable length data types.

serialize

public abstract void serialize(T record,
                               DataOutputView target)
                        throws IOException

Serializes the given record to the given target output view.

Parameters:

record - The record to serialize.

target - The output view to write the serialized data to.

Throws:

IOException - Thrown, if the serialization encountered an I/O related error. Typically raised by the output view, which may have an underlying I/O channel to which it delegates.

deserialize

public abstract T deserialize(DataInputView source)
                       throws IOException

De-serializes a record from the given source input view.

Parameters:

source - The input view from which to read the data.

Returns:

The deserialized element.

Throws:

IOException - Thrown, if the de-serialization encountered an I/O related error. Typically raised by the input view, which may have an underlying I/O channel from which it reads.

deserialize

public abstract T deserialize(T reuse,
                              DataInputView source)
                       throws IOException

De-serializes a record from the given source input view into the given reuse record instance if mutable.

Parameters:

reuse - The record instance into which to de-serialize the data.

source - The input view from which to read the data.

Returns:

The deserialized element.

Throws:

IOException - Thrown, if the de-serialization encountered an I/O related error. Typically raised by the input view, which may have an underlying I/O channel from which it reads.

copy

public abstract void copy(DataInputView source,
                          DataOutputView target)
                   throws IOException

Copies exactly one record from the source input view to the target output view. Whether this operation works on binary data or partially de-serializes the record to determine its length (such as for records of variable length) is up to the implementer. Binary copies are typically faster. A copy of a record containing two integer numbers (8 bytes total) is most efficiently implemented as target.write(source, 8);.

Parameters:

source - The input view from which to read the record.

target - The target output view to which to write the record.

Throws:

IOException - Thrown if any of the two views raises an exception.

equals

public abstract boolean equals(Object obj)

Overrides:

equals in class Object

canEqual

public abstract boolean canEqual(Object obj)

Returns true if the given object can be equaled with this object. If not, it returns false.

Parameters:

obj - Object which wants to take part in the equality relation

Returns:

true if obj can be equaled with this, otherwise false

hashCode

public abstract int hashCode()

Overrides:

hashCode in class Object

snapshotConfiguration

public abstract TypeSerializerConfigSnapshot snapshotConfiguration()

Create a snapshot of the serializer's current configuration to be stored along with the managed state it is registered to (if any - this method is only relevant if this serializer is registered for serialization of managed state).

The configuration snapshot should contain information about the serializer's parameter settings and its serialization format. When a new serializer is registered to serialize the same managed state that this serializer was registered to, the returned configuration snapshot can be used to ensure compatibility of the new serializer and determine if state migration is required.

Returns:

snapshot of the serializer's current configuration (cannot be null).

See Also:

TypeSerializerConfigSnapshot

ensureCompatibility

public abstract CompatibilityResult<T> ensureCompatibility(TypeSerializerConfigSnapshot configSnapshot)

Ensure compatibility of this serializer with a preceding serializer that was registered for serialization of the same managed state (if any - this method is only relevant if this serializer is registered for serialization of managed state). The compatibility check in this method should be performed by inspecting the preceding serializer's configuration snapshot. The method may reconfigure the serializer (if required and possible) so that it may be compatible, or provide a signaling result that informs Flink that state migration is necessary before continuing to use this serializer.

The result can be one of the following:

• CompatibilityResult.compatible(): this signals Flink that this serializer is compatible, or has been reconfigured to be compatible, to continue reading previous data, and that the serialization schema remains the same. No migration needs to be performed.
• CompatibilityResult.requiresMigration(TypeDeserializer): this signals Flink that migration needs to be performed, because this serializer is not compatible, or cannot be reconfigured to be compatible, for previous data. Furthermore, in the case that the preceding serializer cannot be found or restored to read the previous data to perform the migration, the provided convert deserializer can be used as a fallback resort.
• CompatibilityResult.requiresMigration(): this signals Flink that migration needs to be performed, because this serializer is not compatible, or cannot be reconfigured to be compatible, for previous data. If the preceding serializer cannot be found (either its implementation changed or it was removed from the classpath) then the migration will fail due to incapability to read previous data.

Parameters:

configSnapshot - configuration snapshot of a preceding serializer for the same managed state

Returns:

the determined compatibility result (cannot be null).

See Also:

CompatibilityResult