Package org.apache.tinkerpop.gremlin.structure.io.gryo

Class GryoMapper.Builder

java.lang.Object

org.apache.tinkerpop.gremlin.structure.io.gryo.GryoMapper.Builder

All Implemented Interfaces:

Mapper.Builder<GryoMapper.Builder>

Enclosing class:

GryoMapper

public static class GryoMapper.Builder
extends Object
implements Mapper.Builder<GryoMapper.Builder>

A builder to construct a GryoMapper instance.

Method Summary

Modifier and Type	Method	Description
GryoMapper.Builder	addCustom(Class... custom)	Register custom classes to serializes with gryo using default serialization.
GryoMapper.Builder	addCustom(Class clazz, Function<org.apache.tinkerpop.shaded.kryo.Kryo,org.apache.tinkerpop.shaded.kryo.Serializer> functionOfKryo)	Register a custom class to serialize with a custom serializer as returned from a Function.
GryoMapper.Builder	addCustom(Class clazz, SerializerShim serializer)	Register custom class to serialize with a custom serialization shim.
GryoMapper.Builder	addCustom(Class clazz, org.apache.tinkerpop.shaded.kryo.Serializer serializer)	Register custom class to serialize with a custom serialization class.
GryoMapper.Builder	addRegistry(IoRegistry registry)	Adds a vendor supplied IoRegistry to the Mapper.Builder which enables it to check for vendor custom serializers to add to the Mapper.
GryoMapper.Builder	classResolver(Supplier<org.apache.tinkerpop.shaded.kryo.ClassResolver> classResolverSupplier)	Provides a custom Kryo ClassResolver to be supplied to a Kryo instance.
GryoMapper	create()	Creates a GryoMapper.
GryoMapper.Builder	javaSerializationAllowed(boolean javaSerializationAllowed)	When set to false, every registration whose serializer is Kryo's JavaSerializer is dropped, closing the native Java deserialization sink those registrations carry.
GryoMapper.Builder	referenceTracking(boolean referenceTracking)	By default, each appearance of an object in the graph after the first is stored as an integer ordinal.
GryoMapper.Builder	registrationRequired(boolean registrationRequired)	When set to true, all classes serialized by the Kryo instances created from this GryoMapper must have their classes known up front and registered appropriately through this builder.
GryoMapper.Builder	version(GryoVersion version)	The version of Gryo to use in the mapper.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tinkerpop.gremlin.structure.io.Mapper.Builder

addRegistries

Method Detail

addRegistry

public GryoMapper.Builder addRegistry(IoRegistry registry)

Adds a vendor supplied IoRegistry to the Mapper.Builder which enables it to check for vendor custom serializers to add to the Mapper. All Io implementations should expose this method via this Mapper.Builder so that it is compatible with Graph.io(org.apache.tinkerpop.gremlin.structure.io.Io.Builder<I>). Successive calls to this method will add multiple registries. Registry order must be respected when doing so. In other words, data written with IoRegistry A added first and B second must be read by a Mapper with that same registry ordering. Attempting to add B before A will result in errors.

Specified by:

addRegistry in interface Mapper.Builder<GryoMapper.Builder>

version

public GryoMapper.Builder version(GryoVersion version)

The version of Gryo to use in the mapper. Defaults to 1.0. Calls to this method will reset values specified to addCustom(Class, Function) and related overloads.

classResolver

public GryoMapper.Builder classResolver(Supplier<org.apache.tinkerpop.shaded.kryo.ClassResolver> classResolverSupplier)

Provides a custom Kryo ClassResolver to be supplied to a Kryo instance. If this value is not supplied then it will default to the ClassResolver of the provided GryoVersion. To ensure compatibility with Gryo it is highly recommended that objects passed to this method extend that class.

If the ClassResolver implementation share state, then the Supplier should typically create new instances when requested, as the Supplier will be called for each Kryo instance created.

addCustom

public GryoMapper.Builder addCustom(Class... custom)

Register custom classes to serializes with gryo using default serialization. Note that calling this method for a class that is already registered will override that registration.

addCustom

public GryoMapper.Builder addCustom(Class clazz,
                                    org.apache.tinkerpop.shaded.kryo.Serializer serializer)

Register custom class to serialize with a custom serialization class. Note that calling this method for a class that is already registered will override that registration.

addCustom

public GryoMapper.Builder addCustom(Class clazz,
                                    SerializerShim serializer)

Register custom class to serialize with a custom serialization shim.

addCustom

public GryoMapper.Builder addCustom(Class clazz,
                                    Function<org.apache.tinkerpop.shaded.kryo.Kryo,org.apache.tinkerpop.shaded.kryo.Serializer> functionOfKryo)

Register a custom class to serialize with a custom serializer as returned from a Function. Note that calling this method for a class that is already registered will override that registration.

registrationRequired

public GryoMapper.Builder registrationRequired(boolean registrationRequired)

When set to true, all classes serialized by the Kryo instances created from this GryoMapper must have their classes known up front and registered appropriately through this builder. By default this value is true. This approach is more efficient than setting the value to false. It must also stay true when javaSerializationAllowed(boolean) is false, as create() rejects that combination.

Parameters:

registrationRequired - set to true if the classes should be registered up front or false otherwise

See Also:

javaSerializationAllowed(boolean)

javaSerializationAllowed

public GryoMapper.Builder javaSerializationAllowed(boolean javaSerializationAllowed)

When set to false, every registration whose serializer is Kryo's JavaSerializer is dropped, closing the native Java deserialization sink those registrations carry. This builder defaults the value to true, while the paths that read graph documents set it to false for the caller, namely io(), GryoReader, GryoWriter, GryoIo and the Hadoop Gryo formats, so a builder obtained from one of those arrives hardened already. Dropping the registrations narrows what a Gryo document can do while decoding rather than making an untrusted document safe in general, as other registered types still resolve a class named in the stream.

That serializer reads by way of java.io.ObjectInputStream.readObject(), which reconstructs and runs an arbitrary Serializable object graph while decoding, before the graph layer can accept or reject anything. The affected types are mostly TraversalStrategy implementations that a graph document does not need; a stream that carries one now fails with an unregistered class id. Registrations contributed through an IoRegistry or addCustom(...) are covered on the same terms, including those whose serializer is a Function or a class default that resolves to a JavaSerializer. This requires registrationRequired(boolean) to stay true, which create() enforces. Without it a stream may name a class as a string rather than by registered id, and Kryo then resolves that class implicitly with its default serializer, which is a JavaSerializer for any type declaring one. Callers that need the full fidelity for trusted, in-process work should leave this value at true.

A supplied mapper is used as given, so GryoPool, which builds its own and is what OLAP relies on, keeps these registrations and is deliberately out of scope.

Parameters:

javaSerializationAllowed - set to false to drop the JavaSerializer registrations or true to keep them

See Also:

registrationRequired(boolean)

referenceTracking

public GryoMapper.Builder referenceTracking(boolean referenceTracking)

By default, each appearance of an object in the graph after the first is stored as an integer ordinal. This allows multiple references to the same object and cyclic graphs to be serialized. This has a small amount of overhead and can be disabled to save space if it is not needed.

Parameters:

referenceTracking - set to true to enable and false otherwise

create

public GryoMapper create()

Creates a GryoMapper.

Throws:

IllegalStateException - if javaSerializationAllowed(boolean) is false while registrationRequired(boolean) is false, a combination that would not hold the JavaSerializer registrations out