docs/src/dev/io/gryo.asciidoc - tinkerpop - Git at Google

 ////
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 ////
 [[gryo]]
 = Gryo

 image:gremlin-kryo.png[width=400,float=left] Gryo uses the popular link:https://github.com/EsotericSoftware/kryo[Kryo]
 library to handle binary serialization for the JVM. There currently aren't any Kryo implementations in other languages
 so the binding of this format to the JVM is a bit of a limitation, but if building a system on the JVM the use of
 Gryo over other serialization format should yield smaller data sizes than other formats like GraphSON or GraphML,
 improved serialization speed, as well as better support for the various Java data types that might not be supported
 otherwise.

 It is unlikely that Gryo users will try to consume or produce Gryo without using TinkerPop and Kryo classes to help do
 it. Attempting to read or write a byte stream of Gryo without those tools would be challenging, so the depths of
 what the Gryo format looks like in a byte-by-byte perspective will not be discussed here. It is enough to know that
 TinkerPop has Kryo-based serializers for certain classes that it supports and that the bytes written or read must be
 Kryo compliant.

 One of the key aspects of Gryo is that, by default, it requires that all types expected to be used to be registered
 with the `GryoMapper`. There are two ways to do that:

 * On the `GryoMapper.Builder`, use the `addCustom` methods. These methods allow registration of single classes with
 an optional custom serializer.
 * Add a custom `IoRegistry` implementation with the `addRegistry` method on `GryoMapper.Builder`. The `IoRegistry`
 contains registrations that will be supplied to the `GryoMapper`. There is additional documentation on how this works
 in the link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#io-implementations[provider documentation].

 When using `addCustom` or `addRegistry`, it is important to remember that the order in which those methods are called
 is important. The registrations get numeric "registration ids" and their order must match if the the Gryo is expected
 to be compatible. Calls to `addCustom` will be applied first, prior to calls to `addRegistry` (which internally call
 `addCustom`).

 It is possible to disable registration by setting `registrationRequired` on the `GryoMapper.Builder` to `false`, but
 Gryo is less efficient with this feature is turned off.

 Until TinkerPop 3.3.0 there has only been one version of Gryo in 1.0 and the format for that version has generally
 expanded as new releases of TinkerPop have been produced. "Expansion" has generally meant that new types have come to
 be supported over time. The addition of new types means that while Gryo has remained at 1.0, older releases that
 produced Gryo files will not be compatible with newer TinkerPop releases if the newer types are utilized. On the flip
 side, newer release of TinkerPop are fully backward compatible with Gryo produced on older versions of TinkerPop.

 As of TinkerPop 3.3.0, there is now a new version of Gryo in 3.0 that is only partially compatible with 1.0. Attempts
 to use 3.0 serializers with 1.0 serializers will likely lead to failure. For best results, users should always
 utilize the same version of TinkerPop on the client as on the server.

 IMPORTANT: As of 3.6.0, Gryo `MessageSerializer` implementations have been removed from the codebase.

 Both versions of Gryo support all the types defined by GraphSON as well as others that are bound more specifically
 to the JVM. The link:https://github.com/apache/tinkerpop/blob/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoVersion.java[GryoVersion]
 class contains a listing of all the default registered classes.
	////
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	////
	[[gryo]]
	= Gryo

	image:gremlin-kryo.png[width=400,float=left] Gryo uses the popular link:https://github.com/EsotericSoftware/kryo[Kryo]
	library to handle binary serialization for the JVM. There currently aren't any Kryo implementations in other languages
	so the binding of this format to the JVM is a bit of a limitation, but if building a system on the JVM the use of
	Gryo over other serialization format should yield smaller data sizes than other formats like GraphSON or GraphML,
	improved serialization speed, as well as better support for the various Java data types that might not be supported
	otherwise.

	It is unlikely that Gryo users will try to consume or produce Gryo without using TinkerPop and Kryo classes to help do
	it. Attempting to read or write a byte stream of Gryo without those tools would be challenging, so the depths of
	what the Gryo format looks like in a byte-by-byte perspective will not be discussed here. It is enough to know that
	TinkerPop has Kryo-based serializers for certain classes that it supports and that the bytes written or read must be
	Kryo compliant.

	One of the key aspects of Gryo is that, by default, it requires that all types expected to be used to be registered
	with the `GryoMapper`. There are two ways to do that:

	* On the `GryoMapper.Builder`, use the `addCustom` methods. These methods allow registration of single classes with
	an optional custom serializer.
	* Add a custom `IoRegistry` implementation with the `addRegistry` method on `GryoMapper.Builder`. The `IoRegistry`
	contains registrations that will be supplied to the `GryoMapper`. There is additional documentation on how this works
	in the link:https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#io-implementations[provider documentation].

	When using `addCustom` or `addRegistry`, it is important to remember that the order in which those methods are called
	is important. The registrations get numeric "registration ids" and their order must match if the the Gryo is expected
	to be compatible. Calls to `addCustom` will be applied first, prior to calls to `addRegistry` (which internally call
	`addCustom`).

	It is possible to disable registration by setting `registrationRequired` on the `GryoMapper.Builder` to `false`, but
	Gryo is less efficient with this feature is turned off.

	Until TinkerPop 3.3.0 there has only been one version of Gryo in 1.0 and the format for that version has generally
	expanded as new releases of TinkerPop have been produced. "Expansion" has generally meant that new types have come to
	be supported over time. The addition of new types means that while Gryo has remained at 1.0, older releases that
	produced Gryo files will not be compatible with newer TinkerPop releases if the newer types are utilized. On the flip
	side, newer release of TinkerPop are fully backward compatible with Gryo produced on older versions of TinkerPop.

	As of TinkerPop 3.3.0, there is now a new version of Gryo in 3.0 that is only partially compatible with 1.0. Attempts
	to use 3.0 serializers with 1.0 serializers will likely lead to failure. For best results, users should always
	utilize the same version of TinkerPop on the client as on the server.

	IMPORTANT: As of 3.6.0, Gryo `MessageSerializer` implementations have been removed from the codebase.

	Both versions of Gryo support all the types defined by GraphSON as well as others that are bound more specifically
	to the JVM. The link:https://github.com/apache/tinkerpop/blob/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoVersion.java[GryoVersion]
	class contains a listing of all the default registered classes.