Repository: tinkerpop Updated Branches: refs/heads/master 4cab09ddf -> 837b60de0
Remove doc references to GraphSON 2.0 for GLVs GLVs are not bound to GraphSON 2.0 as both support 3.0 on the 3.3.x line. They basically just exclude 1.0. Also moved docs on GLV serialization extensions to the dev docs as that's not really something that users would do. Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/c13bf942 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/c13bf942 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/c13bf942 Branch: refs/heads/master Commit: c13bf94234e4409b6d78138b53ad8d244ae8401c Parents: ea10316 Author: Stephen Mallette <sp...@genoprime.com> Authored: Mon Oct 16 08:25:55 2017 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Mon Oct 16 08:25:55 2017 -0400 ---------------------------------------------------------------------- docs/src/dev/provider/index.asciidoc | 103 ++++++++++++++++++++++ docs/src/reference/gremlin-variants.asciidoc | 95 +------------------- 2 files changed, 105 insertions(+), 93 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/c13bf942/docs/src/dev/provider/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/provider/index.asciidoc b/docs/src/dev/provider/index.asciidoc index c64261f..1479320 100644 --- a/docs/src/dev/provider/index.asciidoc +++ b/docs/src/dev/provider/index.asciidoc @@ -401,6 +401,109 @@ TIP: Consider separating serializer code into its own module, if possible, so th implementation remotely don't need a full dependency on the entire `Graph` - just the IO components and related classes being serialized. +There is an important implication to consider when the addition of a custom serializer. Presumably, the custom +serializer was written for the JVM to be deployed with a `Graph` instance. For example, a graph may expose a +geographical type like a `Point` or something similar. The library that contains `Point` assuming users expected to +deserialize back to a `Point` would need to have the library with `Point` and the "`PointSerializer`" class available +to them. In cases where that deployment approach is not desirable, it is possible to coerce a class like `Point` to +a type that is already in the list of types supported in TinkerPop. For example, `Point` could be coerced one-way to +`Map` of keys "x" and "y". Of course, on the client side, users would have to construct a `Map` for a `Point` which +isn't quite as user-friendly. + +If doing a type coercion is not desired, then it is important to remember that writing a `Point` class and related +serializer in Java is not sufficient for full support of Gremlin, as users of non-JVM Gremlin Language Variants (GLV) +will not be able to consume them. Getting full support would mean writing similar classes for each GLV. While +developing those classes is not hard, it also means more code to support. + +===== Supporting Gremlin-Python IO + +The serialization system of Gremlin-Python provides ways to add new types by creating serializers and deserializers in +Python and registering them with the `RemoteConnection`. + +[source,python] +---- +class MyType(object): + GRAPHSON_PREFIX = "providerx" + GRAPHSON_BASE_TYPE = "MyType" + GRAPHSON_TYPE = GraphSONUtil.formatType(GRAPHSON_PREFIX, GRAPHSON_BASE_TYPE) + + def __init__(self, x, y): + self.x = x + self.y = y + + @classmethod + def objectify(cls, value, reader): + return cls(value['x'], value['y']) + + @classmethod + def dictify(cls, value, writer): + return GraphSONUtil.typedValue(cls.GRAPHSON_BASE_TYPE, + {'x': value.x, 'y': value.y}, + cls.GRAPHSON_PREFIX) + +graphson_reader = GraphSONReader({MyType.GRAPHSON_TYPE: MyType}) +graphson_writer = GraphSONWriter({MyType: MyType}) + +connection = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', + graphson_reader=graphson_reader, + graphson_writer=graphson_writer) +---- + +===== Supporting Gremlin-DotNet IO + +The serialization system of Gremlin-DotNet provides ways to add new types by creating serializers and deserializers in +any .NET language and registering them with the `GremlinClient`. + +[source,csharp] +---- +internal class MyType +{ + public static string GraphsonPrefix = "providerx"; + public static string GraphsonBaseType = "MyType"; + public static string GraphsonType = GraphSONUtil.FormatTypeName(GraphsonPrefix, GraphsonBaseType); + + public MyType(int x, int y) + { + X = x; + Y = y; + } + + public int X { get; } + public int Y { get; } +} + +internal class MyClassWriter : IGraphSONSerializer +{ + public Dictionary<string, dynamic> Dictify(dynamic objectData, GraphSONWriter writer) + { + MyType myType = objectData; + var valueDict = new Dictionary<string, object> + { + {"x", myType.X}, + {"y", myType.Y} + }; + return GraphSONUtil.ToTypedValue(nameof(TestClass), valueDict, MyType.GraphsonPrefix); + } +} + +internal class MyTypeReader : IGraphSONDeserializer +{ + public dynamic Objectify(JToken graphsonObject, GraphSONReader reader) + { + var x = reader.ToObject(graphsonObject["x"]); + var y = reader.ToObject(graphsonObject["y"]); + return new MyType(x, y); + } +} + +var graphsonReader = new GraphSONReader( + new Dictionary<string, IGraphSONDeserializer> {{MyType.GraphsonType, new MyTypeReader()}}); +var graphsonWriter = new GraphSONWriter( + new Dictionary<Type, IGraphSONSerializer> {{typeof(MyType), new MyClassWriter()}}); + +var gremlinClient = new GremlinClient(new GremlinServer("localhost", 8182), graphsonReader, graphsonWriter); +---- + [[remoteconnection-implementations]] ==== RemoteConnection Implementations http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/c13bf942/docs/src/reference/gremlin-variants.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/gremlin-variants.asciidoc b/docs/src/reference/gremlin-variants.asciidoc index 3076c14..bb4bbba 100644 --- a/docs/src/reference/gremlin-variants.asciidoc +++ b/docs/src/reference/gremlin-variants.asciidoc @@ -116,7 +116,7 @@ IMPORTANT: For developers wishing to provide another *driver implementation*, be When Gremlin Server is running, Gremlin-Python can communicate with Gremlin Server. The `conf/gremlin-server-modern-py.yaml` configuration maintains a `GremlinJythonScriptEngine` as well as the appropriate serializers for communicating `Bytecode`. -IMPORTANT: Gremlin-Python is compatible with GraphSON 2.0 only, so this serializer must be configured in Gremlin Server. +IMPORTANT: Gremlin-Python is not compatible with GraphSON 1.0. [source,bash] ---- @@ -308,41 +308,6 @@ g.V().out().map(lambda: "x: len(x.get().value('name'))").sum().toList() <7> The default lambda language is changed back to Gremlin-Python. <8> If the `lambda`-prefix is not provided, then it is appended automatically in order to give a more natural look to the expression. -=== Custom Serialization - -Gremlin-Python provides a GraphSON 2.0 serialization package with the standard Apache TinkerPop `g`-types registered -(see link:http://tinkerpop.apache.org/docs/x.y.z/dev/io/#graphson-2d0[GraphSON 2.0]). It is possible for users to add -new types by creating serializers and deserializers in Python and registering them with the `RemoteConnection`. - -[source,python] ----- -class MyType(object): - GRAPHSON_PREFIX = "providerx" - GRAPHSON_BASE_TYPE = "MyType" - GRAPHSON_TYPE = GraphSONUtil.formatType(GRAPHSON_PREFIX, GRAPHSON_BASE_TYPE) - - def __init__(self, x, y): - self.x = x - self.y = y - - @classmethod - def objectify(cls, value, reader): - return cls(value['x'], value['y']) - - @classmethod - def dictify(cls, value, writer): - return GraphSONUtil.typedValue(cls.GRAPHSON_BASE_TYPE, - {'x': value.x, 'y': value.y}, - cls.GRAPHSON_PREFIX) - -graphson_reader = GraphSONReader({MyType.GRAPHSON_TYPE: MyType}) -graphson_writer = GraphSONWriter({MyType: MyType}) - -connection = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', - graphson_reader=graphson_reader, - graphson_writer=graphson_writer) ----- - [[gremlin-DotNet]] == Gremlin.Net @@ -369,7 +334,7 @@ IMPORTANT: For developers wishing to provide another driver implementation, be s When Gremlin Server is running, Gremlin-DotNet can communicate with Gremlin Server by sending traversals serialized as `Bytecode`. -IMPORTANT: Gremlin-DotNet is compatible with GraphSON 2.0 only, so this serializer must be configured in Gremlin Server. +IMPORTANT: Gremlin-DotNet is not compatible with GraphSON 1.0. A traversal source can be spawned with `RemoteStrategy` from an empty `Graph`. @@ -470,59 +435,3 @@ edgeValueMaps = g.V().OutE().ValueMap(true).ToList(); NOTE: Many of the TraversalStrategy classes in Gremlin-DotNet are proxies to the respective strategy on Apache TinkerPopâs JVM-based Gremlin traversal machine. As such, their `Apply(ITraversal)` method does nothing. However, the strategy is encoded in the Gremlin-DotNet bytecode and transmitted to the Gremlin traversal machine for re-construction machine-side. - -=== Custom Serialization - -Gremlin-DotNet provides a GraphSON 2.0 serialization package with the standard Apache TinkerPop `g`-types registered -(see link:http://tinkerpop.apache.org/docs/x.y.z/dev/io/#graphson-2d0[GraphSON 2.0]). It is possible for users to add new -types by creating serializers and deserializers in C# (or any other .NET language) and registering them with the `GremlinClient`. - -[source,csharp] ----- -internal class MyType -{ - public static string GraphsonPrefix = "providerx"; - public static string GraphsonBaseType = "MyType"; - public static string GraphsonType = GraphSONUtil.FormatTypeName(GraphsonPrefix, GraphsonBaseType); - - public MyType(int x, int y) - { - X = x; - Y = y; - } - - public int X { get; } - public int Y { get; } -} - -internal class MyClassWriter : IGraphSONSerializer -{ - public Dictionary<string, dynamic> Dictify(dynamic objectData, GraphSONWriter writer) - { - MyType myType = objectData; - var valueDict = new Dictionary<string, object> - { - {"x", myType.X}, - {"y", myType.Y} - }; - return GraphSONUtil.ToTypedValue(nameof(TestClass), valueDict, MyType.GraphsonPrefix); - } -} - -internal class MyTypeReader : IGraphSONDeserializer -{ - public dynamic Objectify(JToken graphsonObject, GraphSONReader reader) - { - var x = reader.ToObject(graphsonObject["x"]); - var y = reader.ToObject(graphsonObject["y"]); - return new MyType(x, y); - } -} - -var graphsonReader = new GraphSONReader( - new Dictionary<string, IGraphSONDeserializer> {{MyType.GraphsonType, new MyTypeReader()}}); -var graphsonWriter = new GraphSONWriter( - new Dictionary<Type, IGraphSONSerializer> {{typeof(MyType), new MyClassWriter()}}); - -var gremlinClient = new GremlinClient(new GremlinServer("localhost", 8182), graphsonReader, graphsonWriter); -----
