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>

All Implemented Interfaces:

Comparator<FieldSerializer.CachedField>

public class TaggedFieldSerializer<T>
extends FieldSerializer<T>

Serializes objects using direct field assignment for fields that have a @Tag(int) annotation. This provides backward compatibility so new fields can be added. TaggedFieldSerializer has two advantages over VersionFieldSerializer : 1) fields can be renamed and 2) fields marked with the @Deprecated annotation will be ignored when reading old bytes and won't be written to new bytes. Deprecation effectively removes the field from serialization, though the field and @Tag annotation must remain in the class. Deprecated fields can optionally be made private and/or renamed so they don't clutter the class (eg, ignored, ignored2). For these reasons, TaggedFieldSerializer generally provides more flexibility for classes to evolve. The downside is that it has a small amount of additional overhead compared to VersionFieldSerializer (an additional varint per field).

Forward compatibility is optionally supported by enabling setSkipUnknownTags(boolean), which allows it to skip reading unknown tagged fields, which are presumably new fields added in future versions of an application. The data is only forward compatible if the newly added fields are tagged with TaggedFieldSerializer.Tag.annexed() set true, which comes with the cost of chunked encoding. When annexed fields are encountered during the read or write process of an object, a buffer is allocated to perform the chunked encoding.

Tag values must be entirely unique, even among a class and its superclass(es). An IllegalArgumentException will be thrown by Kryo.register(Class) (and its overloads) if duplicate Tag values are encountered.

Author:

Nathan Sweet

See Also:

VersionFieldSerializer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	TaggedFieldSerializer.Tag Marks a field for serialization.

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

FieldSerializer.Bind, FieldSerializer.CachedField<X>, FieldSerializer.CachedFieldFactory, FieldSerializer.CachedFieldNameStrategy, FieldSerializer.Optional

Field Summary

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

config, removedFields

Constructor Summary

Constructors

Constructor and Description
TaggedFieldSerializer(Kryo kryo, Class type)

Method Summary

Modifier and Type	Method and Description
protected void	initializeCachedFields()
boolean	isIgnoreUnkownTags() Deprecated. See setIgnoreUnknownTags(boolean) for information.
boolean	isSkipUnknownTags()
T	read(Kryo kryo, Input input, Class<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	setIgnoreUnknownTags(boolean ignoreUnknownTags) Deprecated. The ignoreUnknownTags feature is deprecated and the functionality is disabled, as it is an invalid means of preserving forward compatibility. See setSkipUnknownTags(boolean) for an alternate means.
void	setSkipUnknownTags(boolean skipUnknownTags) Set whether TaggedFieldSerializer should attempt to skip reading the data of unknown tags, rather than throwing a KryoException.
void	write(Kryo kryo, Output output, T object) This method can be called for different fields having the same type.

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

compare, copy, create, createCopy, getCachedFieldName, getCopyTransient, getField, getFields, getGenerics, getKryo, getSerializeTransient, getTransientFields, getType, getUseAsmEnabled, getUseMemRegions, rebuildCachedFields, rebuildCachedFields, setCopyTransient, setFieldsAsAccessible, setFieldsCanBeNull, setFixedFieldTypes, setGenerics, setIgnoreSyntheticFields, setOptimizedGenerics, setSerializeTransient, setUseAsm

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

Methods inherited from interface java.util.Comparator

comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Constructor Detail

TaggedFieldSerializer

public TaggedFieldSerializer(Kryo kryo,
                             Class type)

Method Detail

setSkipUnknownTags

public void setSkipUnknownTags(boolean skipUnknownTags)

Set whether TaggedFieldSerializer should attempt to skip reading the data of unknown tags, rather than throwing a KryoException. Data can be skipped if it is tagged with TaggedFieldSerializer.Tag.annexed() set true. This enables forward compatibility.

By default, this setting matches the value of TaggedFieldSerializerConfig.isSkipUnknownTags() in Kryo.getTaggedFieldSerializerConfig(), which is false by default.

Parameters:

skipUnknownTags - If true, unknown field tags will be skipped, with the assumption that they are future tagged values with TaggedFieldSerializer.Tag.annexed() set true. If false KryoException will be thrown whenever unknown tags are encountered.

isSkipUnknownTags

public boolean isSkipUnknownTags()

Returns:

Whether the TaggedFieldSerializers should attempt to skip reading the data of unknown tags, rather than throwing a KryoException. See setSkipUnknownTags(boolean).

initializeCachedFields

protected void initializeCachedFields()

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: FieldSerializer

This method can be called for different fields having the same type. Even though the raw type is the same, if the type is generic, it could happen that different concrete classes are used to instantiate it. Therefore, in case of different instantiation parameters, the fields analysis should be repeated. TODO: Cache serializer instances generated for a given set of generic parameters. Reuse it later instead of recomputing every time.

Overrides:

write in class FieldSerializer<T>

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

read

public T read(Kryo kryo,
              Input input,
              Class<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.

setIgnoreUnknownTags

@Deprecated
public void setIgnoreUnknownTags(boolean ignoreUnknownTags)

Deprecated. The ignoreUnknownTags feature is deprecated and the functionality is disabled, as it is an invalid means of preserving forward compatibility. See setSkipUnknownTags(boolean) for an alternate means.

Parameters:

ignoreUnknownTags - This setting is now ignored.

isIgnoreUnkownTags

@Deprecated
public boolean isIgnoreUnkownTags()

Deprecated. See setIgnoreUnknownTags(boolean) for information.

Returns:

Always returns false, as this feature has been disabled.