Package com.esotericsoftware.kryo.serializers

Class TaggedFieldSerializer<T>

java.lang.Object

com.esotericsoftware.kryo.Serializer<T>

com.esotericsoftware.kryo.serializers.FieldSerializer<T>

com.esotericsoftware.kryo.serializers.TaggedFieldSerializer<T>

public class TaggedFieldSerializer<T>
extends FieldSerializer<T>

Serializes objects using direct field assignment for fields that have a @Tag(int) annotation, providing backward compatibility and optional forward compatibility. This means fields can be added or renamed and optionally removed without invalidating previously serialized bytes. Changing the type of a field is not supported.

Fields are identified by the TaggedFieldSerializer.Tag annotation. Fields can be renamed without affecting serialization. Field tag values must be unique, both within a class and all its super classes. An exception is thrown if duplicate tag values are encountered.

The forward and backward compatibility and serialization performance depend on TaggedFieldSerializer.TaggedFieldSerializerConfig.setReadUnknownTagData(boolean) and TaggedFieldSerializer.TaggedFieldSerializerConfig.setChunkedEncoding(boolean). Additionally, a varint is written before each field for the tag value.

If readUnknownTagData and chunkedEncoding are false, fields must not be removed but the Deprecated annotation can be applied. Deprecated fields are read when reading old bytes but aren't written to new bytes. Classes can evolve by reading the values of deprecated fields and writing them elsewhere. Fields can be renamed and/or made private to reduce clutter in the class (eg, ignored1, ignored2).

Compared to VersionFieldSerializer, TaggedFieldSerializer allows renaming and deprecating fields, so has more flexibility for classes to evolve. This comes at the cost of one varint per field.

Author:

Nathan Sweet

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TaggedFieldSerializer.Tag	Marks a field for serialization.
static class	TaggedFieldSerializer.TaggedFieldSerializerConfig	Configuration for TaggedFieldSerializer instances.

Nested classes/interfaces inherited from class com.esotericsoftware.kryo.serializers.FieldSerializer

FieldSerializer.Bind, FieldSerializer.CachedField, FieldSerializer.FieldSerializerConfig, FieldSerializer.NotNull, FieldSerializer.Optional

Constructor Summary

Constructors

Constructor	Description
TaggedFieldSerializer(Kryo kryo, Class type)
TaggedFieldSerializer(Kryo kryo, Class type, TaggedFieldSerializer.TaggedFieldSerializerConfig config)

Method Summary

Modifier and Type	Method	Description
TaggedFieldSerializer.TaggedFieldSerializerConfig	getTaggedFieldSerializerConfig()
protected void	initializeCachedFields()	Called when FieldSerializer.getFields() and FieldSerializer.getCopyFields() have been repopulated.
T	read(Kryo kryo, Input input, Class<? extends T> type)	Reads bytes and returns a new object of the specified concrete type.
void	removeField(FieldSerializer.CachedField field)	Removes a field so that it won't be serialized.
void	removeField(String fieldName)	Removes a field so that it won't be serialized.
void	write(Kryo kryo, Output output, T object)	Writes the bytes for the object to the output.
protected void	writeHeader(Kryo kryo, Output output, T object)	Can be overidden to write data needed for FieldSerializer.create(Kryo, Input, Class).

Methods inherited from class com.esotericsoftware.kryo.serializers.FieldSerializer

copy, create, createCopy, getCopyFields, getField, getFields, getFieldSerializerConfig, getKryo, getType, log, popTypeVariables, pushTypeVariables, updateFields

Methods inherited from class com.esotericsoftware.kryo.Serializer

getAcceptsNull, isImmutable, setAcceptsNull, setImmutable

Methods inherited from class java.lang.Object

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

Constructor Detail

TaggedFieldSerializer

public TaggedFieldSerializer(Kryo kryo,
                             Class type)

TaggedFieldSerializer

public TaggedFieldSerializer(Kryo kryo,
                             Class type,
                             TaggedFieldSerializer.TaggedFieldSerializerConfig config)

Method Detail

initializeCachedFields

protected void initializeCachedFields()

Description copied from class: FieldSerializer

Called when FieldSerializer.getFields() and FieldSerializer.getCopyFields() have been repopulated. Subclasses can override this method to configure or remove cached fields.

Overrides:

initializeCachedFields in class FieldSerializer<T>

removeField

public void removeField(String fieldName)

Description copied from class: FieldSerializer

Removes a field so that it won't be serialized.

Overrides:

removeField in class FieldSerializer<T>

removeField

public void removeField(FieldSerializer.CachedField field)

Description copied from class: FieldSerializer

Removes a field so that it won't be serialized.

Overrides:

removeField in class FieldSerializer<T>

write

public void write(Kryo kryo,
                  Output output,
                  T object)

Description copied from class: Serializer

Writes the bytes for the object to the output.

This method should not be called directly, instead this serializer can be passed to Kryo write methods that accept a serialier.

Overrides:

write in class FieldSerializer<T>

object - May be null if Serializer.getAcceptsNull() is true.

writeHeader

protected void writeHeader(Kryo kryo,
                           Output output,
                           T object)

Can be overidden to write data needed for FieldSerializer.create(Kryo, Input, Class). The default implementation does nothing.

read

public T read(Kryo kryo,
              Input input,
              Class<? extends T> type)

Description copied from class: Serializer

Reads bytes and returns a new object of the specified concrete type.

Before Kryo can be used to read child objects, Kryo.reference(Object) must be called with the parent object to ensure it can be referenced by the child objects. Any serializer that uses Kryo to read a child object may need to be reentrant.

This method should not be called directly, instead this serializer can be passed to Kryo read methods that accept a serialier.

Overrides:

read in class FieldSerializer<T>

Returns:

May be null if Serializer.getAcceptsNull() is true.

getTaggedFieldSerializerConfig

public TaggedFieldSerializer.TaggedFieldSerializerConfig getTaggedFieldSerializerConfig()