com.esotericsoftware.kryo.serializers

Class FieldSerializer<T>

java.lang.Object

com.esotericsoftware.kryo.Serializer<T>

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

All Implemented Interfaces:

Comparator<FieldSerializer.CachedField>

Direct Known Subclasses:

CompatibleFieldSerializer, TaggedFieldSerializer, VersionFieldSerializer

public class FieldSerializer<T>
extends Serializer<T>
implements Comparator<FieldSerializer.CachedField>

Serializes objects using direct field assignment. FieldSerializer is generic and can serialize most classes without any configuration. It is efficient and writes only the field data, without any extra information. It does not support adding, removing, or changing the type of fields without invalidating previously serialized bytes. This can be acceptable in many situations, such as when sending data over a network, but may not be a good choice for long term data storage because the Java classes cannot evolve. Because FieldSerializer attempts to read and write non-public fields by default, it is important to evaluate each class that will be serialized. If fields are public, bytecode generation will be used instead of reflection.

Author:

Nathan Sweet , Roman Levenstein

See Also:

Serializer, Kryo.register(Class, Serializer), VersionFieldSerializer, TaggedFieldSerializer, CompatibleFieldSerializer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FieldSerializer.Bind Used to annotate fields with a specific Kryo serializer.
static class	FieldSerializer.CachedField<X> Controls how a field will be serialized.
static interface	FieldSerializer.CachedFieldFactory
static interface	FieldSerializer.CachedFieldNameStrategy
static interface	FieldSerializer.Optional Indicates a field should be ignored when its declaring class is registered unless the context has a value set for the specified key.

Field Summary

Fields

Modifier and Type	Field and Description
protected FieldSerializerConfig	config
protected HashSet<FieldSerializer.CachedField>	removedFields

Constructor Summary

Constructors

Modifier	Constructor and Description
	FieldSerializer(Kryo kryo, Class type)
	FieldSerializer(Kryo kryo, Class type, Class[] generics)
protected	FieldSerializer(Kryo kryo, Class type, Class[] generics, FieldSerializerConfig config)

Method Summary

Modifier and Type	Method and Description
int	compare(FieldSerializer.CachedField o1, FieldSerializer.CachedField o2)
T	copy(Kryo kryo, T original) Returns a copy of the specified object.
protected T	create(Kryo kryo, Input input, Class<T> type) Used by read(Kryo, Input, Class) to create the new object.
protected T	createCopy(Kryo kryo, T original) Used by copy(Kryo, Object) to create the new object.
protected String	getCachedFieldName(FieldSerializer.CachedField cachedField)
boolean	getCopyTransient()
FieldSerializer.CachedField	getField(String fieldName) Allows specific fields to be optimized.
FieldSerializer.CachedField[]	getFields() Get all fields controlled by this FieldSerializer
Class[]	getGenerics() Get generic type parameters of the class controlled by this serializer.
Kryo	getKryo()
boolean	getSerializeTransient()
FieldSerializer.CachedField[]	getTransientFields() Get all transient fields controlled by this FieldSerializer
Class	getType()
boolean	getUseAsmEnabled()
boolean	getUseMemRegions()
protected void	initializeCachedFields()
T	read(Kryo kryo, Input input, Class<T> type) Reads bytes and returns a new object of the specified concrete type.
protected void	rebuildCachedFields() Called when the list of cached fields must be rebuilt.
protected void	rebuildCachedFields(boolean minorRebuild) Rebuilds the list of cached fields.
void	removeField(FieldSerializer.CachedField removeField) 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	setCopyTransient(boolean setCopyTransient)
void	setFieldsAsAccessible(boolean setFieldsAsAccessible) Controls which fields are serialized.
void	setFieldsCanBeNull(boolean fieldsCanBeNull) Sets the default value for FieldSerializer.CachedField.setCanBeNull(boolean).
void	setFixedFieldTypes(boolean fixedFieldTypes) Sets the default value for FieldSerializer.CachedField.setClass(Class) to the field's declared type.
void	setGenerics(Kryo kryo, Class[] generics) Sets the generic types of the field or method this serializer will be used for on the next call to read or write.
void	setIgnoreSyntheticFields(boolean ignoreSyntheticFields) Controls if synthetic fields are serialized.
void	setOptimizedGenerics(boolean setOptimizedGenerics) Controls if the serialization of generics should be optimized for smaller size.
void	setSerializeTransient(boolean setSerializeTransient)
void	setUseAsm(boolean setUseAsm) Controls whether ASM should be used.
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.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

Field Detail

config

protected final FieldSerializerConfig config

removedFields

protected HashSet<FieldSerializer.CachedField> removedFields

Constructor Detail

FieldSerializer

public FieldSerializer(Kryo kryo,
                       Class type)

FieldSerializer

public FieldSerializer(Kryo kryo,
                       Class type,
                       Class[] generics)

FieldSerializer

protected FieldSerializer(Kryo kryo,
                          Class type,
                          Class[] generics,
                          FieldSerializerConfig config)

Method Detail

rebuildCachedFields

protected void rebuildCachedFields()

Called when the list of cached fields must be rebuilt. This is done any time settings are changed that affect which fields will be used. It is called from the constructor for FieldSerializer, but not for subclasses. Subclasses must call this from their constructor.

rebuildCachedFields

protected void rebuildCachedFields(boolean minorRebuild)

Rebuilds the list of cached fields.

Parameters:

minorRebuild - if set, processing due to changes in generic type parameters will be optimized

setGenerics

public void setGenerics(Kryo kryo,
                        Class[] generics)

Description copied from class: Serializer

Sets the generic types of the field or method this serializer will be used for on the next call to read or write. Subsequent calls to read and write must not use this generic type information. The default implementation does nothing. Subclasses may use the information provided to this method for more efficient serialization, eg to use the same type for all items in a list.

Overrides:

setGenerics in class Serializer<T>

generics - Some (but never all) elements may be null if there is no generic type information at that index.

getGenerics

public Class[] getGenerics()

Get generic type parameters of the class controlled by this serializer.

Returns:

generic type parameters or null, if there are none.

initializeCachedFields

protected void initializeCachedFields()

compare

public int compare(FieldSerializer.CachedField o1,
                   FieldSerializer.CachedField o2)

Specified by:

compare in interface Comparator<FieldSerializer.CachedField>

setFieldsCanBeNull

public void setFieldsCanBeNull(boolean fieldsCanBeNull)

Sets the default value for FieldSerializer.CachedField.setCanBeNull(boolean). Calling this method resets the cached fields.

Parameters:

fieldsCanBeNull - False if none of the fields are null. Saves 0-1 byte per field. True if it is not known (default).

setFieldsAsAccessible

public void setFieldsAsAccessible(boolean setFieldsAsAccessible)

Controls which fields are serialized. Calling this method resets the cached fields.

Parameters:

setFieldsAsAccessible - If true, all non-transient fields (inlcuding private fields) will be serialized and set as accessible if necessary (default). If false, only fields in the public API will be serialized.

setIgnoreSyntheticFields

public void setIgnoreSyntheticFields(boolean ignoreSyntheticFields)

Controls if synthetic fields are serialized. Default is true. Calling this method resets the cached fields.

Parameters:

ignoreSyntheticFields - If true, only non-synthetic fields will be serialized.

setFixedFieldTypes

public void setFixedFieldTypes(boolean fixedFieldTypes)

Sets the default value for FieldSerializer.CachedField.setClass(Class) to the field's declared type. This allows FieldSerializer to be more efficient, since it knows field values will not be a subclass of their declared type. Default is false. Calling this method resets the cached fields.

setUseAsm

public void setUseAsm(boolean setUseAsm)

Controls whether ASM should be used. Calling this method resets the cached fields.

Parameters:

setUseAsm - If true, ASM will be used for fast serialization. If false, Unsafe will be used (default)

setCopyTransient

public void setCopyTransient(boolean setCopyTransient)

setSerializeTransient

public void setSerializeTransient(boolean setSerializeTransient)

setOptimizedGenerics

public void setOptimizedGenerics(boolean setOptimizedGenerics)

Controls if the serialization of generics should be optimized for smaller size.

Important: This setting changes the serialized representation, so that data can be deserialized only with if this setting is the same as it was for serialization.

Parameters:

setOptimizedGenerics - If true, the serialization of generics will be optimize for smaller size (default: false)

write

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

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.

Specified by:

write in class Serializer<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.

Specified by:

read in class Serializer<T>

Returns:

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

create

protected T create(Kryo kryo,
                   Input input,
                   Class<T> type)

Used by read(Kryo, Input, Class) to create the new object. This can be overridden to customize object creation, eg to call a constructor with arguments. The default implementation uses Kryo.newInstance(Class).

getField

public FieldSerializer.CachedField getField(String fieldName)

Allows specific fields to be optimized.

getCachedFieldName

protected String getCachedFieldName(FieldSerializer.CachedField cachedField)

removeField

public void removeField(String fieldName)

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

removeField

public void removeField(FieldSerializer.CachedField removeField)

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

getFields

public FieldSerializer.CachedField[] getFields()

Get all fields controlled by this FieldSerializer

Returns:

all fields controlled by this FieldSerializer

getTransientFields

public FieldSerializer.CachedField[] getTransientFields()

Get all transient fields controlled by this FieldSerializer

Returns:

all transient fields controlled by this FieldSerializer

getType

public Class getType()

getKryo

public Kryo getKryo()

getUseAsmEnabled

public boolean getUseAsmEnabled()

getUseMemRegions

public boolean getUseMemRegions()

getCopyTransient

public boolean getCopyTransient()

getSerializeTransient

public boolean getSerializeTransient()

createCopy

protected T createCopy(Kryo kryo,
                       T original)

Used by copy(Kryo, Object) to create the new object. This can be overridden to customize object creation, eg to call a constructor with arguments. The default implementation uses Kryo.newInstance(Class).

copy

public T copy(Kryo kryo,
              T original)

Description copied from class: Serializer

Returns a copy of the specified object. The default implementation returns the original if Serializer.isImmutable() is true, else throws KryoException. Subclasses should override this method if needed to support Kryo.copy(Object).

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

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

Overrides:

copy in class Serializer<T>