org.nustaq.serialization

Class FSTConfiguration

java.lang.Object

org.nustaq.serialization.FSTConfiguration

public class FSTConfiguration
extends Object

Created with IntelliJ IDEA. User: ruedi Date: 18.11.12 Time: 20:41 Holds a serialization configuration/metadata. Reuse this class !!! construction is very expensive. (just keep static instances around or use thread locals)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FSTConfiguration.StreamCoderFactory

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	isAndroid

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FSTConfiguration()

Method Summary

Modifier and Type	Method and Description
byte[]	asByteArray(Object object) convenience.
Object	asObject(byte[] b) convenience
byte[]	asSharedByteArray(Object object, int[] length) Warning: avoids allocation + copying.
int	calcObjectSizeBytesNotAUtility(Object obj) for optimization purposes, do not use to benchmark processing time or in a regular program as this methods creates a temporary binaryoutputstream and serializes the object in order to measure the size.
void	clearCaches() clear cached softref's and ThreadLocal.
static FSTConfiguration	createAndroidDefaultConfiguration() Configuration for use on Android.
static FSTConfiguration	createDefaultConfiguration() the standard FSTConfiguration
static FSTConfiguration	createFastBinaryConfiguration() Returns a configuration using Unsafe to read write data
static FSTConfiguration	createMinBinConfiguration() Warning: MinBin contains full metainformation (fieldnames,..), so its way slower than the other configs.
FSTDecoder	createStreamDecoder()
FSTEncoder	createStreamEncoder()
static FSTConfiguration	createStructConfiguration() special configuration used internally for struct emulation
<T> T	deepCopy(T metadata)
Object	getCachedObject(Class cl)
String	getClassForCPName(String name)
FSTClazzInfo	getClassInfo(Class type)
ClassLoader	getClassLoader()
FSTClazzNameRegistry	getClassRegistry()
FSTClazzInfo	getClazzInfo(Class rowClass)
FSTClazzInfoRegistry	getCLInfoRegistry()
String	getCPNameForClass(Class cl) get cross platform symbolic class identifier
byte[]	getCrossPlatformBinaryCache(String symbolicName)
static FSTConfiguration	getDefaultConfiguration()
FSTClassInstantiator	getInstantiator(Class clazz)
FSTObjectInput	getObjectInput()
FSTObjectInput	getObjectInput(byte[] arr)
FSTObjectInput	getObjectInput(byte[] arr, int len) take the given array as input. the array is NOT copied
FSTObjectInput	getObjectInput(InputStream in) utility for thread safety and reuse.
FSTObjectOutput	getObjectOutput()
FSTObjectOutput	getObjectOutput(byte[] outByte)
FSTObjectOutput	getObjectOutput(OutputStream out) utility for thread safety and reuse.
FSTConfiguration.StreamCoderFactory	getStreamCoderFactory()
protected static FSTConfiguration	initDefaultFstConfigurationInternal(FSTConfiguration conf)
boolean	isCrossPlatform()
boolean	isForceClzInit()
boolean	isForceSerializable()
boolean	isPreferSpeed() ignored currently
boolean	isShareReferences()
boolean	isStructMode() special for structs
void	registerClass(Class... c) Preregister a class (use at init time).
void	registerCrossPlatformClassBinaryCache(String fulLQName, byte[] binary)
void	registerCrossPlatformClassMapping(String[][] keysAndVals) init right after creation of configuration, not during operation as it is not threadsafe regarding mutation currently only for minbin serialization
void	registerCrossPlatformClassMapping(String shortName, String fqName)
void	registerCrossPlatformClassMappingUseSimpleName(Class[] classes) init right after creation of configuration, not during operation as it is not threadsafe regarding mutation
void	registerCrossPlatformClassMappingUseSimpleName(List<Class> classes)
void	registerSerializer(Class clazz, FSTObjectSerializer ser, boolean alsoForAllSubclasses) register a custom serializer for a given class or the class and all of its subclasses.
void	returnObject(Object cached) reuse heavy weight objects.
void	setClassLoader(ClassLoader classLoader)
void	setCrossPlatform(boolean crossPlatform)
FSTConfiguration	setForceClzInit(boolean forceClzInit) always execute default fields init, even if no transients (so would get overwritten anyway) required for lossy codecs (kson)
FSTConfiguration	setForceSerializable(boolean forceSerializable) treat unserializable classes same as if they would be serializable.
void	setInstantiator(FSTClassInstantiator instantiator)
void	setPreferSpeed(boolean preferSpeed) this options lets FST favour speed of encoding over size of the encoded object.
void	setSerializerRegistryDelegate(FSTSerializerRegistryDelegate del) patch default serializer lookup. set to null to delete.
void	setShareReferences(boolean shareReferences) if false, identical objects will get serialized twice.
void	setStreamCoderFactory(FSTConfiguration.StreamCoderFactory streamCoderFactory) allows to use subclassed stream codecs.
void	setStructMode(boolean ignoreSerialInterfaces) ignores all serialization related interfaces (Serializable, Externalizable) and serializes all classes using the default scheme.

Methods inherited from class java.lang.Object

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

Field Detail

isAndroid

public static boolean isAndroid

Constructor Detail

FSTConfiguration

protected FSTConfiguration()

Method Detail

isForceClzInit

public boolean isForceClzInit()

setForceClzInit

public FSTConfiguration setForceClzInit(boolean forceClzInit)

always execute default fields init, even if no transients (so would get overwritten anyway) required for lossy codecs (kson)

Parameters:

forceClzInit -

Returns:

getInstantiator

public FSTClassInstantiator getInstantiator(Class clazz)

setInstantiator

public void setInstantiator(FSTClassInstantiator instantiator)

getDefaultConfiguration

public static FSTConfiguration getDefaultConfiguration()

setClassLoader

public void setClassLoader(ClassLoader classLoader)

createMinBinConfiguration

public static FSTConfiguration createMinBinConfiguration()

Warning: MinBin contains full metainformation (fieldnames,..), so its way slower than the other configs. It should be used in case of cross language (e.g. java - javascript) serialization only. Additionally you can read MinBin serialized streams without access to original classes. See MBPrinter on an example on how to read a MinBin stream without having access to original classes. Useful for cross language serialization/long term archiving. Warning: MinBin serialization ('binary JSon') is much slower than the other serialization configurations.

Returns:

a configuration to encode MinBin format.

createAndroidDefaultConfiguration

public static FSTConfiguration createAndroidDefaultConfiguration()

Configuration for use on Android. Its binary compatible with getDefaultConfiguration(). So one can write on server with getDefaultConf and read on mobile client with getAndroidConf().

Returns:

createDefaultConfiguration

public static FSTConfiguration createDefaultConfiguration()

the standard FSTConfiguration. - safe (no unsafe r/w) - platform independent byte order - moderate compression note that if you are just read/write from/to byte arrays, its faster to use DefaultCoder. This should be used most of the time.

Returns:

initDefaultFstConfigurationInternal

protected static FSTConfiguration initDefaultFstConfigurationInternal(FSTConfiguration conf)

createFastBinaryConfiguration

public static FSTConfiguration createFastBinaryConfiguration()

Returns a configuration using Unsafe to read write data. - platform dependent byte order - no value compression attempts - makes heavy use of Unsafe, which can be dangerous in case of version conflicts Use only in case it makes a significant difference and you absolutely need the performance gain. Performance gains depend on data. There are cases where this is even slower, in some scenarios (many native arrays) it can be several times faster. see also OffHeapCoder, OnHeapCoder.

registerSerializer

public void registerSerializer(Class clazz,
                               FSTObjectSerializer ser,
                               boolean alsoForAllSubclasses)

register a custom serializer for a given class or the class and all of its subclasses. Serializers must be configured identical on read/write side and should be set before actually making use of the Configuration.

Parameters:

clazz -

ser -

alsoForAllSubclasses -

createStructConfiguration

public static FSTConfiguration createStructConfiguration()

special configuration used internally for struct emulation

Returns:

getStreamCoderFactory

public FSTConfiguration.StreamCoderFactory getStreamCoderFactory()

setStreamCoderFactory

public void setStreamCoderFactory(FSTConfiguration.StreamCoderFactory streamCoderFactory)

allows to use subclassed stream codecs. Can also be used to change class loading behaviour, as clasForName is part of a codec's interface. e.g. new StreamCoderFactory() {

Parameters:

streamCoderFactory -

returnObject

public void returnObject(Object cached)

reuse heavy weight objects. If a FSTStream is closed, objects are returned and can be reused by new stream instances. the objects are held in soft references, so there should be no memory issues. FIXME: point of contention !

Parameters:

cached -

isPreferSpeed

public boolean isPreferSpeed()

ignored currently

Returns:

setPreferSpeed

public void setPreferSpeed(boolean preferSpeed)

this options lets FST favour speed of encoding over size of the encoded object. Warning: this option alters the format of the written stream, so both reader and writer should have the same setting, else exceptions will occur

Parameters:

preferSpeed -

calcObjectSizeBytesNotAUtility

public int calcObjectSizeBytesNotAUtility(Object obj)
                                   throws IOException

for optimization purposes, do not use to benchmark processing time or in a regular program as this methods creates a temporary binaryoutputstream and serializes the object in order to measure the size.

Throws:

IOException

setSerializerRegistryDelegate

public void setSerializerRegistryDelegate(FSTSerializerRegistryDelegate del)

patch default serializer lookup. set to null to delete. Should be set prior to any serialization going on (serializer lookup is cached).

Parameters:

del -

getCachedObject

public Object getCachedObject(Class cl)

isForceSerializable

public boolean isForceSerializable()

setForceSerializable

public FSTConfiguration setForceSerializable(boolean forceSerializable)

treat unserializable classes same as if they would be serializable.

Parameters:

forceSerializable -

clearCaches

public void clearCaches()

clear cached softref's and ThreadLocal. Use if you won't read/write objects anytime soon.

isShareReferences

public boolean isShareReferences()

setShareReferences

public void setShareReferences(boolean shareReferences)

if false, identical objects will get serialized twice. Gains speed as long there are no double objects/cyclic references (typical for small snippets as used in e.g. RPC)

Parameters:

shareReferences -

registerClass

public void registerClass(Class... c)

Preregister a class (use at init time). This avoids having to write class names. Its a very simple and effective optimization (frequently > 2 times faster for small objects). Read and write side need to have classes preregistered in the exact same order. The list does not have to be complete. Just add your most frequently serialized classes here to get significant gains in speed and smaller serialized representation size.

getClassRegistry

public FSTClazzNameRegistry getClassRegistry()

getCLInfoRegistry

public FSTClazzInfoRegistry getCLInfoRegistry()

getClassLoader

public ClassLoader getClassLoader()

getClassInfo

public FSTClazzInfo getClassInfo(Class type)

getObjectInput

public FSTObjectInput getObjectInput(InputStream in)

utility for thread safety and reuse. Do not close the resulting stream. However you should close the given InputStream 'in'

Parameters:

in -

Returns:

getObjectInput

public FSTObjectInput getObjectInput()

getObjectInput

public FSTObjectInput getObjectInput(byte[] arr)

getObjectInput

public FSTObjectInput getObjectInput(byte[] arr,
                                     int len)

take the given array as input. the array is NOT copied

Parameters:

arr -

len -

Returns:

getObjectOutput

public FSTObjectOutput getObjectOutput(OutputStream out)

utility for thread safety and reuse. Do not close the resulting stream. However you should close the given OutputStream 'out'

Parameters:

out - - can be null (temp bytearrays stream is created then)

Returns:

getObjectOutput

public FSTObjectOutput getObjectOutput()

Returns:

a recycled outputstream reusing its last recently used byte[] buffer

getObjectOutput

public FSTObjectOutput getObjectOutput(byte[] outByte)

setStructMode

public void setStructMode(boolean ignoreSerialInterfaces)

ignores all serialization related interfaces (Serializable, Externalizable) and serializes all classes using the default scheme. Warning: this is a special mode of operation which fail serializing/deserializing many standard JDK classes.

Parameters:

ignoreSerialInterfaces -

isStructMode

public boolean isStructMode()

special for structs

Returns:

getClazzInfo

public FSTClazzInfo getClazzInfo(Class rowClass)

setCrossPlatform

public void setCrossPlatform(boolean crossPlatform)

isCrossPlatform

public boolean isCrossPlatform()

deepCopy

public <T> T deepCopy(T metadata)

createStreamEncoder

public FSTEncoder createStreamEncoder()

createStreamDecoder

public FSTDecoder createStreamDecoder()

registerCrossPlatformClassBinaryCache

public void registerCrossPlatformClassBinaryCache(String fulLQName,
                                                  byte[] binary)

getCrossPlatformBinaryCache

public byte[] getCrossPlatformBinaryCache(String symbolicName)

registerCrossPlatformClassMapping

public void registerCrossPlatformClassMapping(String[][] keysAndVals)

init right after creation of configuration, not during operation as it is not threadsafe regarding mutation currently only for minbin serialization

Parameters:

keysAndVals - { { "symbolicName", "fullQualifiedClazzName" }, .. }

registerCrossPlatformClassMapping

public void registerCrossPlatformClassMapping(String shortName,
                                              String fqName)

registerCrossPlatformClassMappingUseSimpleName

public void registerCrossPlatformClassMappingUseSimpleName(Class[] classes)

init right after creation of configuration, not during operation as it is not threadsafe regarding mutation

registerCrossPlatformClassMappingUseSimpleName

public void registerCrossPlatformClassMappingUseSimpleName(List<Class> classes)

getCPNameForClass

public String getCPNameForClass(Class cl)

get cross platform symbolic class identifier

Parameters:

cl -

Returns:

getClassForCPName

public String getClassForCPName(String name)

asObject

public Object asObject(byte[] b)

convenience

asByteArray

public byte[] asByteArray(Object object)

convenience. (object must be serialiable unless fstconfiguration with appropriate settings is used)

asSharedByteArray

public byte[] asSharedByteArray(Object object,
                                int[] length)

Warning: avoids allocation + copying. The returned byteArray is a direct pointer to underlying buffer. the int length[] is expected to have at least on element. The buffer can be larger than written data, therefore length[0] will contain written length. The buffer content must be used (e.g. sent to network, copied to offheap) before doing another asByteArray on the current Thread.