com.esotericsoftware.kryo

Class Kryo

java.lang.Object

com.esotericsoftware.kryo.Kryo

public class Kryo
extends java.lang.Object

Maps classes to serializers so object graphs can be serialized automatically.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	Kryo.Closure
static class	Kryo.DefaultInstantiatorStrategy
(package private) static class	Kryo.DefaultSerializerEntry

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	asmEnabled Tells if ASM-based backend should be used by new serializer instances created using this Kryo instance.
private boolean	autoReset
private java.lang.ClassLoader	classLoader
private ClassResolver	classResolver
private ObjectMap	context
private int	copyDepth
private boolean	copyReferences
private boolean	copyShallow
private SerializerFactory	defaultSerializer
private java.util.ArrayList<Kryo.DefaultSerializerEntry>	defaultSerializers
private int	depth
private Generics	genericsScope
private ObjectMap	graphContext
private int	lowPriorityDefaultSerializerCount
private int	maxDepth
private java.lang.Object	needsCopyReference
private int	nextRegisterID
private static int	NO_REF
static byte	NOT_NULL
static byte	NULL
private IdentityMap	originalToCopy
private java.lang.Object	readObject
private IntArray	readReferenceIds
private static int	REF
private ReferenceResolver	referenceResolver
private boolean	references
private boolean	registrationRequired
private org.objenesis.strategy.InstantiatorStrategy	strategy
private StreamFactory	streamFactory
private java.lang.Thread	thread

Constructor Summary

Constructors

Constructor and Description
Kryo() Creates a new Kryo with a DefaultClassResolver and a MapReferenceResolver.
Kryo(ClassResolver classResolver, ReferenceResolver referenceResolver)
Kryo(ClassResolver classResolver, ReferenceResolver referenceResolver, StreamFactory streamFactory)
Kryo(ReferenceResolver referenceResolver) Creates a new Kryo with a DefaultClassResolver.

Method Summary

Modifier and Type	Method and Description
void	addDefaultSerializer(java.lang.Class type, java.lang.Class<? extends Serializer> serializerClass) Instances of the specified class will use the specified serializer when register(Class) or register(Class, int) are called.
void	addDefaultSerializer(java.lang.Class type, Serializer serializer) Instances of the specified class will use the specified serializer when register(Class) or register(Class, int) are called.
void	addDefaultSerializer(java.lang.Class type, SerializerFactory serializerFactory) Instances of the specified class will use the specified factory to create a serializer when register(Class) or register(Class, int) are called.
private void	beginObject()
<T> T	copy(T object) Returns a deep copy of the object.
<T> T	copy(T object, Serializer serializer) Returns a deep copy of the object using the specified serializer.
<T> T	copyShallow(T object) Returns a shallow copy of the object.
<T> T	copyShallow(T object, Serializer serializer) Returns a shallow copy of the object using the specified serializer.
boolean	getAsmEnabled()
java.lang.ClassLoader	getClassLoader()
ClassResolver	getClassResolver()
ObjectMap	getContext() Name/value pairs that are available to all serializers.
Serializer	getDefaultSerializer(java.lang.Class type) Returns the best matching serializer for a class.
protected Serializer	getDefaultSerializerForAnnotatedType(java.lang.Class type)
int	getDepth() Returns the number of child objects away from the object graph root.
Generics	getGenericsScope()
ObjectMap	getGraphContext() Name/value pairs that are available to all serializers and are cleared after each object graph is serialized or deserialized.
org.objenesis.strategy.InstantiatorStrategy	getInstantiatorStrategy()
int	getNextRegistrationId() Returns the lowest, next available integer ID.
IdentityMap	getOriginalToCopyMap() Returns the internal map of original to copy objects when a copy method is used.
ReferenceResolver	getReferenceResolver()
boolean	getReferences()
Registration	getRegistration(java.lang.Class type) If the class is not registered and setRegistrationRequired(boolean) is false, it is automatically registered using the default serializer.
Registration	getRegistration(int classID)
Serializer	getSerializer(java.lang.Class type) Returns the serializer for the registration for the specified class.
StreamFactory	getStreamFactory()
boolean	isClousre(java.lang.Class type) Returns true if the specified type is a closure.
boolean	isFinal(java.lang.Class type) Returns true if the specified type is final.
boolean	isRegistrationRequired()
protected Serializer	newDefaultSerializer(java.lang.Class type) Called by getDefaultSerializer(Class) when no default serializers matched the type.
<T> T	newInstance(java.lang.Class<T> type) Creates a new instance of a class using Registration.getInstantiator().
protected org.objenesis.instantiator.ObjectInstantiator	newInstantiator(java.lang.Class type) Returns a new instantiator for creating new instances of the specified type.
void	popGenericsScope()
void	pushGenericsScope(java.lang.Class type, Generics generics)
Registration	readClass(Input input) Reads a class and returns its registration.
java.lang.Object	readClassAndObject(Input input) Reads the class and object or null using the registered serializer.
<T> T	readObject(Input input, java.lang.Class<T> type) Reads an object using the registered serializer.
<T> T	readObject(Input input, java.lang.Class<T> type, Serializer serializer) Reads an object using the specified serializer.
<T> T	readObjectOrNull(Input input, java.lang.Class<T> type) Reads an object or null using the registered serializer.
<T> T	readObjectOrNull(Input input, java.lang.Class<T> type, Serializer serializer) Reads an object or null using the specified serializer.
(package private) int	readReferenceOrNull(Input input, java.lang.Class type, boolean mayBeNull) Returns REF if a reference to a previously read object was read, which is stored in readObject.
void	reference(java.lang.Object object) Called by Serializer.read(Kryo, Input, Class) and Serializer.copy(Kryo, Object) before Kryo can be used to deserialize or copy child objects.
Registration	register(java.lang.Class type) Registers the class using the lowest, next available integer ID and the default serializer.
Registration	register(java.lang.Class type, int id) Registers the class using the specified ID and the default serializer.
Registration	register(java.lang.Class type, Serializer serializer) Registers the class using the lowest, next available integer ID and the specified serializer.
Registration	register(java.lang.Class type, Serializer serializer, int id) Registers the class using the specified ID and serializer.
Registration	register(Registration registration) Stores the specified registration.
void	reset() Resets unregistered class names, references to previously serialized or deserialized objects, and the graph context.
void	setAsmEnabled(boolean flag) Tells Kryo, if ASM-based backend should be used by new serializer instances created using this Kryo instance.
void	setAutoReset(boolean autoReset) If true (the default), reset() is called automatically after an entire object graph has been read or written.
void	setClassLoader(java.lang.ClassLoader classLoader) Sets the classloader to resolve unregistered class names to classes.
void	setCopyReferences(boolean copyReferences) If true, when copy(Object) and other copy methods encounter an object for the first time the object is copied and on subsequent encounters the copied object is used.
void	setDefaultSerializer(java.lang.Class<? extends Serializer> serializer) Sets the serializer to use when no default serializers match an object's type.
void	setDefaultSerializer(SerializerFactory serializer) Sets the serializer factory to use when no default serializers match an object's type.
void	setInstantiatorStrategy(org.objenesis.strategy.InstantiatorStrategy strategy) Sets the strategy used by newInstantiator(Class) for creating objects.
void	setMaxDepth(int maxDepth) Sets the maxiumum depth of an object graph.
void	setReferenceResolver(ReferenceResolver referenceResolver) Sets the reference resolver and enables references.
boolean	setReferences(boolean references) If true, each appearance of an object in the graph after the first is stored as an integer ordinal.
void	setRegistrationRequired(boolean registrationRequired) If true, an exception is thrown when an unregistered class is encountered.
void	setStreamFactory(StreamFactory streamFactory)
Registration	writeClass(Output output, java.lang.Class type) Writes a class and returns its registration.
void	writeClassAndObject(Output output, java.lang.Object object) Writes the class and object or null using the registered serializer.
void	writeObject(Output output, java.lang.Object object) Writes an object using the registered serializer.
void	writeObject(Output output, java.lang.Object object, Serializer serializer) Writes an object using the specified serializer.
void	writeObjectOrNull(Output output, java.lang.Object object, java.lang.Class type) Writes an object or null using the registered serializer for the specified type.
void	writeObjectOrNull(Output output, java.lang.Object object, Serializer serializer) Writes an object or null using the specified serializer.
(package private) boolean	writeReferenceOrNull(Output output, java.lang.Object object, boolean mayBeNull)

Methods inherited from class java.lang.Object

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

Field Detail

NULL

public static final byte NULL

See Also:

Constant Field Values

NOT_NULL

public static final byte NOT_NULL

See Also:

Constant Field Values

REF

private static final int REF

See Also:

Constant Field Values

NO_REF

private static final int NO_REF

See Also:

Constant Field Values

defaultSerializer

private SerializerFactory defaultSerializer

defaultSerializers

private final java.util.ArrayList<Kryo.DefaultSerializerEntry> defaultSerializers

lowPriorityDefaultSerializerCount

private final int lowPriorityDefaultSerializerCount

classResolver

private final ClassResolver classResolver

nextRegisterID

private int nextRegisterID

classLoader

private java.lang.ClassLoader classLoader

strategy

private org.objenesis.strategy.InstantiatorStrategy strategy

registrationRequired

private boolean registrationRequired

depth

private int depth

maxDepth

private int maxDepth

autoReset

private boolean autoReset

thread

private volatile java.lang.Thread thread

context

private ObjectMap context

graphContext

private ObjectMap graphContext

referenceResolver

private ReferenceResolver referenceResolver

readReferenceIds

private final IntArray readReferenceIds

references

private boolean references

copyReferences

private boolean copyReferences

readObject

private java.lang.Object readObject

copyDepth

private int copyDepth

copyShallow

private boolean copyShallow

originalToCopy

private IdentityMap originalToCopy

needsCopyReference

private java.lang.Object needsCopyReference

genericsScope

private Generics genericsScope

asmEnabled

private boolean asmEnabled

Tells if ASM-based backend should be used by new serializer instances created using this Kryo instance.

streamFactory

private StreamFactory streamFactory

Constructor Detail

Kryo

public Kryo()

Creates a new Kryo with a DefaultClassResolver and a MapReferenceResolver.

Kryo

public Kryo(ReferenceResolver referenceResolver)

Creates a new Kryo with a DefaultClassResolver.

Parameters:

referenceResolver - May be null to disable references.

Kryo

public Kryo(ClassResolver classResolver,
            ReferenceResolver referenceResolver)

Parameters:

referenceResolver - May be null to disable references.

Kryo

public Kryo(ClassResolver classResolver,
            ReferenceResolver referenceResolver,
            StreamFactory streamFactory)

Parameters:

referenceResolver - May be null to disable references.

Method Detail

setDefaultSerializer

public void setDefaultSerializer(SerializerFactory serializer)

Sets the serializer factory to use when no default serializers match an object's type. Default is ReflectionSerializerFactory with FieldSerializer.

See Also:

newDefaultSerializer(Class)

setDefaultSerializer

public void setDefaultSerializer(java.lang.Class<? extends Serializer> serializer)

Sets the serializer to use when no default serializers match an object's type. Default is FieldSerializer.

See Also:

newDefaultSerializer(Class)

addDefaultSerializer

public void addDefaultSerializer(java.lang.Class type,
                                 Serializer serializer)

Instances of the specified class will use the specified serializer when register(Class) or register(Class, int) are called.

See Also:

setDefaultSerializer(Class)

addDefaultSerializer

public void addDefaultSerializer(java.lang.Class type,
                                 SerializerFactory serializerFactory)

Instances of the specified class will use the specified factory to create a serializer when register(Class) or register(Class, int) are called.

See Also:

setDefaultSerializer(Class)

addDefaultSerializer

public void addDefaultSerializer(java.lang.Class type,
                                 java.lang.Class<? extends Serializer> serializerClass)

Instances of the specified class will use the specified serializer when register(Class) or register(Class, int) are called. Serializer instances are created as needed via ReflectionSerializerFactory.makeSerializer(Kryo, Class, Class). By default, the following classes have a default serializer set:

boolean	Boolean	byte	Byte	char
Character	short	Short	int	Integer
long	Long	float	Float	double
Double	String	byte[]	char[]	short[]
int[]	long[]	float[]	double[]	String[]
Object[]	Map	BigInteger	BigDecimal	KryoSerializable
Collection	Date	Collections.emptyList	Collections.singleton	Currency
StringBuilder	Enum	Collections.emptyMap	Collections.emptySet	Calendar
StringBuffer	Class	Collections.singletonList	Collections.singletonMap	TimeZone
TreeMap	EnumSet

Note that the order default serializers are added is important for a class that may match multiple types. The above default serializers always have a lower priority than subsequent default serializers that are added.

getDefaultSerializer

public Serializer getDefaultSerializer(java.lang.Class type)

Returns the best matching serializer for a class. This method can be overridden to implement custom logic to choose a serializer.

getDefaultSerializerForAnnotatedType

protected Serializer getDefaultSerializerForAnnotatedType(java.lang.Class type)

newDefaultSerializer

protected Serializer newDefaultSerializer(java.lang.Class type)

Called by getDefaultSerializer(Class) when no default serializers matched the type. Subclasses can override this method to customize behavior. The default implementation calls SerializerFactory.makeSerializer(Kryo, Class) using the default serializer.

register

public Registration register(java.lang.Class type)

Registers the class using the lowest, next available integer ID and the default serializer. If the class is already registered, no change will be made and the existing registration will be returned. Registering a primitive also affects the corresponding primitive wrapper.

Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this method. The order must be the same at deserialization as it was for serialization.

register

public Registration register(java.lang.Class type,
                             int id)

Registers the class using the specified ID and the default serializer. If the class is already registered this has no effect and the existing registration is returned. Registering a primitive also affects the corresponding primitive wrapper.

IDs must be the same at deserialization as they were for serialization.

Parameters:

id - Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but these IDs can be repurposed.

register

public Registration register(java.lang.Class type,
                             Serializer serializer)

Registers the class using the lowest, next available integer ID and the specified serializer. If the class is already registered, the existing entry is updated with the new serializer. Registering a primitive also affects the corresponding primitive wrapper.

Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this method. The order must be the same at deserialization as it was for serialization.

register

public Registration register(java.lang.Class type,
                             Serializer serializer,
                             int id)

Registers the class using the specified ID and serializer. Providing an ID that is already in use by the same type will cause the old entry to be overwritten. Registering a primitive also affects the corresponding primitive wrapper.

IDs must be the same at deserialization as they were for serialization.

Parameters:

id - Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but these IDs can be repurposed.

register

public Registration register(Registration registration)

Stores the specified registration. If the ID is already in use by the same type, the old entry is overwritten. Registering a primitive also affects the corresponding primitive wrapper.

IDs must be the same at deserialization as they were for serialization.

Registration can be suclassed to efficiently store per type information, accessible in serializers via getRegistration(Class).

getNextRegistrationId

public int getNextRegistrationId()

Returns the lowest, next available integer ID.

getRegistration

public Registration getRegistration(java.lang.Class type)

If the class is not registered and setRegistrationRequired(boolean) is false, it is automatically registered using the default serializer.

Throws:

java.lang.IllegalArgumentException - if the class is not registered and setRegistrationRequired(boolean) is true.

See Also:

ClassResolver.getRegistration(Class)

getRegistration

public Registration getRegistration(int classID)

See Also:

ClassResolver.getRegistration(int)

getSerializer

public Serializer getSerializer(java.lang.Class type)

Returns the serializer for the registration for the specified class.

See Also:

getRegistration(Class), Registration.getSerializer()

writeClass

public Registration writeClass(Output output,
                               java.lang.Class type)

Writes a class and returns its registration.

Parameters:

type - May be null.

Returns:

Will be null if type is null.

See Also:

ClassResolver.writeClass(Output, Class)

writeObject

public void writeObject(Output output,
                        java.lang.Object object)

Writes an object using the registered serializer.

writeObject

public void writeObject(Output output,
                        java.lang.Object object,
                        Serializer serializer)

Writes an object using the specified serializer. The registered serializer is ignored.

writeObjectOrNull

public void writeObjectOrNull(Output output,
                              java.lang.Object object,
                              java.lang.Class type)

Writes an object or null using the registered serializer for the specified type.

Parameters:

object - May be null.

writeObjectOrNull

public void writeObjectOrNull(Output output,
                              java.lang.Object object,
                              Serializer serializer)

Writes an object or null using the specified serializer. The registered serializer is ignored.

Parameters:

object - May be null.

writeClassAndObject

public void writeClassAndObject(Output output,
                                java.lang.Object object)

Writes the class and object or null using the registered serializer.

Parameters:

object - May be null.

writeReferenceOrNull

boolean writeReferenceOrNull(Output output,
                             java.lang.Object object,
                             boolean mayBeNull)

Parameters:

object - May be null if mayBeNull is true.

Returns:

true if no bytes need to be written for the object.

readClass

public Registration readClass(Input input)

Reads a class and returns its registration.

Returns:

May be null.

See Also:

ClassResolver.readClass(Input)

readObject

public <T> T readObject(Input input,
                        java.lang.Class<T> type)

Reads an object using the registered serializer.

readObject

public <T> T readObject(Input input,
                        java.lang.Class<T> type,
                        Serializer serializer)

Reads an object using the specified serializer. The registered serializer is ignored.

readObjectOrNull

public <T> T readObjectOrNull(Input input,
                              java.lang.Class<T> type)

Reads an object or null using the registered serializer.

Returns:

May be null.

readObjectOrNull

public <T> T readObjectOrNull(Input input,
                              java.lang.Class<T> type,
                              Serializer serializer)

Reads an object or null using the specified serializer. The registered serializer is ignored.

Returns:

May be null.

readClassAndObject

public java.lang.Object readClassAndObject(Input input)

Reads the class and object or null using the registered serializer.

Returns:

May be null.

readReferenceOrNull

int readReferenceOrNull(Input input,
                        java.lang.Class type,
                        boolean mayBeNull)

Returns REF if a reference to a previously read object was read, which is stored in readObject. Returns a stack size (> 0) if a reference ID has been put on the stack.

reference

public void reference(java.lang.Object object)

Called by Serializer.read(Kryo, Input, Class) and Serializer.copy(Kryo, Object) before Kryo can be used to deserialize or copy child objects. Calling this method is unnecessary if Kryo is not used to deserialize or copy child objects.

Parameters:

object - May be null, unless calling this method from Serializer.copy(Kryo, Object).

reset

public void reset()

Resets unregistered class names, references to previously serialized or deserialized objects, and the graph context. If auto reset is true, this method is called automatically when an object graph has been completely serialized or deserialized. If overridden, the super method must be called.

copy

public <T> T copy(T object)

Returns a deep copy of the object. Serializers for the classes involved must support Serializer.copy(Kryo, Object).

Parameters:

object - May be null.

copy

public <T> T copy(T object,
                  Serializer serializer)

Returns a deep copy of the object using the specified serializer. Serializers for the classes involved must support Serializer.copy(Kryo, Object).

Parameters:

object - May be null.

copyShallow

public <T> T copyShallow(T object)

Returns a shallow copy of the object. Serializers for the classes involved must support Serializer.copy(Kryo, Object).

Parameters:

object - May be null.

copyShallow

public <T> T copyShallow(T object,
                         Serializer serializer)

Returns a shallow copy of the object using the specified serializer. Serializers for the classes involved must support Serializer.copy(Kryo, Object).

Parameters:

object - May be null.

beginObject

private void beginObject()

getClassResolver

public ClassResolver getClassResolver()

getReferenceResolver

public ReferenceResolver getReferenceResolver()

Returns:

May be null.

setClassLoader

public void setClassLoader(java.lang.ClassLoader classLoader)

Sets the classloader to resolve unregistered class names to classes. The default is the loader that loaded the Kryo class.

getClassLoader

public java.lang.ClassLoader getClassLoader()

setRegistrationRequired

public void setRegistrationRequired(boolean registrationRequired)

If true, an exception is thrown when an unregistered class is encountered. Default is false.

If false, when an unregistered class is encountered, its fully qualified class name will be serialized and the default serializer for the class used to serialize the object. Subsequent appearances of the class within the same object graph are serialized as an int id.

Registered classes are serialized as an int id, avoiding the overhead of serializing the class name, but have the drawback of needing to know the classes to be serialized up front.

isRegistrationRequired

public boolean isRegistrationRequired()

setReferences

public boolean setReferences(boolean references)

If true, each appearance of an object in the graph after the first is stored as an integer ordinal. When set to true, MapReferenceResolver is used. This enables references to the same object and cyclic graphs to be serialized, but typically adds overhead of one byte per object. Default is true.

Returns:

The previous value.

setCopyReferences

public void setCopyReferences(boolean copyReferences)

If true, when copy(Object) and other copy methods encounter an object for the first time the object is copied and on subsequent encounters the copied object is used. If false, the overhead of tracking which objects have already been copied is avoided because each object is copied every time it is encountered, however a stack overflow will occur if an object graph is copied that contains a circular reference. Default is true.

setReferenceResolver

public void setReferenceResolver(ReferenceResolver referenceResolver)

Sets the reference resolver and enables references.

getReferences

public boolean getReferences()

setInstantiatorStrategy

public void setInstantiatorStrategy(org.objenesis.strategy.InstantiatorStrategy strategy)

Sets the strategy used by newInstantiator(Class) for creating objects. See StdInstantiatorStrategy to create objects via without calling any constructor. See SerializingInstantiatorStrategy to mimic Java's built-in serialization.

Parameters:

strategy - May be null.

getInstantiatorStrategy

public org.objenesis.strategy.InstantiatorStrategy getInstantiatorStrategy()

newInstantiator

protected org.objenesis.instantiator.ObjectInstantiator newInstantiator(java.lang.Class type)

Returns a new instantiator for creating new instances of the specified type. By default, an instantiator is returned that uses reflection if the class has a zero argument constructor, an exception is thrown. If a strategy is set, it will be used instead of throwing an exception.

newInstance

public <T> T newInstance(java.lang.Class<T> type)

Creates a new instance of a class using Registration.getInstantiator(). If the registration's instantiator is null, a new one is set using newInstantiator(Class).

getContext

public ObjectMap getContext()

Name/value pairs that are available to all serializers.

getGraphContext

public ObjectMap getGraphContext()

Name/value pairs that are available to all serializers and are cleared after each object graph is serialized or deserialized.

getDepth

public int getDepth()

Returns the number of child objects away from the object graph root.

getOriginalToCopyMap

public IdentityMap getOriginalToCopyMap()

Returns the internal map of original to copy objects when a copy method is used. This can be used after a copy to map old objects to the copies, however it is cleared automatically by reset() so this is only useful when setAutoReset(boolean) is false.

setAutoReset

public void setAutoReset(boolean autoReset)

If true (the default), reset() is called automatically after an entire object graph has been read or written. If false, reset() must be called manually, which allows unregistered class names, references, and other information to span multiple object graphs.

setMaxDepth

public void setMaxDepth(int maxDepth)

Sets the maxiumum depth of an object graph. This can be used to prevent malicious data from causing a stack overflow. Default is Integer.MAX_VALUE.

isFinal

public boolean isFinal(java.lang.Class type)

Returns true if the specified type is final. Final types can be serialized more efficiently because they are non-polymorphic.

This can be overridden to force non-final classes to be treated as final. Eg, if an application uses ArrayList extensively but never uses an ArrayList subclass, treating ArrayList as final could allow FieldSerializer to save 1-2 bytes per ArrayList field.

isClousre

public boolean isClousre(java.lang.Class type)

Returns true if the specified type is a closure.

This can be overridden to support alternative implementations of clousres. Current version supports Oracle's Java8 only

pushGenericsScope

public void pushGenericsScope(java.lang.Class type,
                              Generics generics)

popGenericsScope

public void popGenericsScope()

getGenericsScope

public Generics getGenericsScope()

getStreamFactory

public StreamFactory getStreamFactory()

setStreamFactory

public void setStreamFactory(StreamFactory streamFactory)

setAsmEnabled

public void setAsmEnabled(boolean flag)

Tells Kryo, if ASM-based backend should be used by new serializer instances created using this Kryo instance. Already existing serializer instances are not affected by this setting.

By default, Kryo uses ASM-based backend.

Parameters:

flag - if true, ASM-based backend will be used. Otherwise Unsafe-based backend could be used by some serializers, e.g. FieldSerializer

getAsmEnabled

public boolean getAsmEnabled()