tinkerpop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dkupp...@apache.org
Subject [20/50] tinkerpop git commit: Improved upgrade docs around IO CTR
Date Fri, 04 Aug 2017 16:59:00 GMT
Improved upgrade docs around IO CTR


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/2116819c
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/2116819c
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/2116819c

Branch: refs/heads/TINKERPOP-1682
Commit: 2116819c8ff111e80eff937a6ccab1a62d9786d6
Parents: 89b35b3
Author: Stephen Mallette <spmva@genoprime.com>
Authored: Fri Jul 21 06:43:57 2017 -0400
Committer: Stephen Mallette <spmva@genoprime.com>
Committed: Fri Jul 21 06:43:57 2017 -0400

----------------------------------------------------------------------
 docs/src/upgrade/release-3.3.x.asciidoc | 151 ++++++++++++++++++---------
 1 file changed, 104 insertions(+), 47 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/2116819c/docs/src/upgrade/release-3.3.x.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/upgrade/release-3.3.x.asciidoc b/docs/src/upgrade/release-3.3.x.asciidoc
index bddcebc..2f2f400 100644
--- a/docs/src/upgrade/release-3.3.x.asciidoc
+++ b/docs/src/upgrade/release-3.3.x.asciidoc
@@ -32,13 +32,106 @@ Please see the link:https://github.com/apache/tinkerpop/blob/3.3.0/CHANGELOG.asc
 Upgrading for Users
 ~~~~~~~~~~~~~~~~~~~
 
-GraphSON 2.0
-^^^^^^^^^^^^
+Packaged Data Files
+^^^^^^^^^^^^^^^^^^^
+
+TinkerPop has always packaged sample graphs with its zip distributions. As of 3.3.0, the
distributions will only
+include Gryo 3.0, GraphSON 3.0 and GraphML (which is unversioned) files. Other versions are
not included, but could
+obviously be generated using the IO API directly.
+
+GraphTraversal Has-Methods Re-Organized
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`GraphTraversal.hasXXX()`, where `XXX` is `Id`, `Label`, `Key`, `Value`, was faulty in that
they relied on calling an
+intermediate method for flattening `Object[]` arguments and thus, yielding a non 1-to-1 correspondence
between `GraphTraversal`
+and `Bytecode`. This has been remedied. Most users will not notice this change. Perhaps only
some users that may use
+Java reflection over `GraphTraversal` might have a simple problem.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1520[TINKERPOP-1520]
+
+Changes to IO
+^^^^^^^^^^^^^
+
+*WILL NEED TO WRITE SOMETHING MORE COHESIVE HERE - JUST LISTING STUFF FOR RIGHT NOW*
+
+* Gryo incompatibilities with 3.2.x:
+** `RequestMessage`
+** `ResponseMessage`
+** `TraversalMetrics`
+* GraphSON
+** embedTypes is gone, use typeInfo setting. will default to no types for GraphSON 1.0 and
partial types for graphson 2.0 TINKERPOP-1700
+
+Gryo 3.0
+++++++++
+
+With Gryo, TinkerPop skips version 2.0 and goes right to 3.0 (to maintain better parity with
GraphSON versioning).
+Gryo 3.0 fixes a number of inconsistencies with Gryo 1.0 and hopefully marks a point where
Gryo is better versioned
+over time. Gryo 3.0 is not compatible with Gryo 1.0 and is now the default version of Gryo
exposed by TinkerPop in
+Gremlin Server and IO.
+
+It isn't hard to switch back to use of Gryo 1.0 if necessary. Here is the approach for writing
an entire graph:
+
+[source,java]
+----
+Graph graph = TinkerFactory.createModern();
+GryoMapper mapper = graph.io(IoCore.gryo()).mapper().version(GryoVersion.V1_0).create()
+try (OutputStream os = new FileOutputStream("tinkerpop-modern.json")) {
+    graph.io(IoCore.gryo()).writer().mapper(mapper).create().writeGraph(os, graph)
+}
+
+final Graph newGraph = TinkerGraph.open();
+try (InputStream stream = new FileInputStream("tinkerpop-modern.json")) {
+    newGraph.io(IoCore.gryo()).reader().mapper(mapper).create().readGraph(stream, newGraph);
+}
+----
+
+Gremlin Server configurations don't include Gryo 1.0 by default:
+
+[source,yaml]
+----
+serializers:
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]
}}             # application/vnd.gremlin-v3.0+gryo
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config:
{ serializeResultToString: true }}                                                       
               # application/vnd.gremlin-v3.0+gryo-stringd
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]
}}         # application/json
+----
 
-TODO - RE-READ THIS WHOLE SECTION - IT MIGHT BE A MESS WITH GRAPHSON 3.0 CHANGES COMING IN
-SHOULD PROBABLY FOLD THESE CHANGES DOWN INTO THE "Changes to IO" SECTION AND ONE SOLID SECTION
+but adding an entry as follows will add it back:
 
-Both TinkerGraph and Gremlin Server have been defaulted to work with GraphSON 2.0. For TinkerGraph
this means that
+[source,yaml]
+----
+serializers:
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV1d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0]
}}             # application/vnd.gremlin-v1.0+gryo
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]
}}             # application/vnd.gremlin-v3.0+gryo
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config:
{ serializeResultToString: true }}                                                       
               # application/vnd.gremlin-v3.0+gryo-stringd
+  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]
}}         # application/json
+----
+
+To use Gryo 1.0 with the Java driver, just specify the 1.0 serializer directly:
+
+[source,java]
+----
+GryoMapper.Builder builder = GryoMapper.build().
+        version(GryoVersion.V1_0).
+        addRegistry(TinkerIoRegistryV1d0.instance());
+Cluster cluster = Cluster.build().serializer(GryoMessageSerializerV1d0(builder));
+----
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1698[TINKERPOP-1698]
+
+GraphSON 3.0
+++++++++++++
+
+GraphSON 3.0 finishes what GraphSON 2.0 began by taking the extra step to include the following
types: `g:Map`,
+`g:List` and `g:Set`. With these types it is now possible to get expected Gremlin results
in GLVs just as one would
+if using Java. This is especially true of the `g:Map` type, which allows non-string keys
values, something not allowed
+in regular JSON maps. This allows for common traversals like `g.V().groupCount()` to work,
where the traversal groups
+on a `Vertex` or some other complex object.
+
+Note that GraphSON 3.0 does not have an option to be without types. This was a feature of
1.0 and 2.0, but it is no
+longer supported. There is little point to such a feature as we see more movement toward
GLVs, which require types,
+and less usage of scripts with custom parsing of results.
+
+Both TinkerGraph and Gremlin Server have been defaulted to work with GraphSON 3.0. For TinkerGraph
this means that
 the following commands:
 
 [source,java]
@@ -50,8 +143,8 @@ final Graph newGraph = TinkerGraph.open();
 newGraph.io(IoCore.graphson()).readGraph("tinkerpop-modern.json");
 ----
 
-will write and read GraphSON 2.0 format rather than 1.0. To use 1.0 format simply set the
`version()` on the
-appropriate builder methods:
+will write and read GraphSON 3.0 format rather than 1.0. To use 1.0 (or 2.0 for that matter)
format simply set the
+`version()` on the appropriate builder methods:
 
 [source,java]
 ----
@@ -63,7 +156,7 @@ try (OutputStream os = new FileOutputStream("tinkerpop-modern.json")) {
 
 final Graph newGraph = TinkerGraph.open();
 try (InputStream stream = new FileInputStream("tinkerpop-modern.json")) {
-    newGraph.io(IoCore.graphson()).reader().mapper(mapper).vertexIdKey("name").create().readGraph(stream,
newGraph);
+    newGraph.io(IoCore.graphson()).reader().mapper(mapper).create().readGraph(stream, newGraph);
 }
 ----
 
@@ -89,45 +182,9 @@ It is possible to bring back the original configuration for `application/json`
b
   - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config:
{ ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0]
 }}        # application/json
 ----
 
-See: link:https://issues.apache.org/jira/browse/TINKERPOP-1414[TINKERPOP-1414]
-
-Packaged Data Files
-^^^^^^^^^^^^^^^^^^^
-
-TinkerPop has always packaged sample graphs with its zip distributions. As of 3.3.0, the
distributions will only
-include Gryo 3.0, GraphSON 3.0 and GraphML (which is unversioned) files. Other versions are
not included, but could
-obviously be generated using the IO API directly.
-
-GraphTraversal Has-Methods Re-Organized
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-`GraphTraversal.hasXXX()`, where `XXX` is `Id`, `Label`, `Key`, `Value`, was faulty in that
they relied on calling an
-intermediate method for flattening `Object[]` arguments and thus, yielding a non 1-to-1 correspondence
between `GraphTraversal`
-and `Bytecode`. This has been remedied. Most users will not notice this change. Perhaps only
some users that may use
-Java reflection over `GraphTraversal` might have a simple problem.
-
-See: link:https://issues.apache.org/jira/browse/TINKERPOP-1520[TINKERPOP-1520]
-
-Changes to IO
-^^^^^^^^^^^^^
-
-*WILL NEED TO WRITE SOMETHING MORE COHESIVE HERE - JUST LISTING STUFF FOR RIGHT NOW*
-
-* Gryo incompatibilities with 3.2.x:
-** `RequestMessage`
-** `ResponseMessage`
-** `TraversalMetrics`
-* GraphSON
-** embedTypes is gone, use typeInfo setting. will default to no types for GraphSON 1.0 and
partial types for graphson 2.0 TINKERPOP-1700
-
-Gryo 3.0
-++++++++
-
-Gryo 3.0 fixes a number of inconsistencies with Gryo 1.0 and hopefully marks a point where
Gryo is better versioned
-over time. Gryo 3.0 is not compatible with Gryo 1.0 and is now the default version of Gryo
exposed by TinkerPop in
-Gremlin Server and IO.
-
-See: link:https://issues.apache.org/jira/browse/TINKERPOP-1698[TINKERPOP-1698]
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1414[TINKERPOP-1414],
+link:https://issues.apache.org/jira/browse/TINKERPOP-1427[TINKERPOP-1427],
+link:https://issues.apache.org/jira/browse/TINKERPOP-1574[TINKERPOP-1574]
 
 Graphite and Ganglia
 ^^^^^^^^^^^^^^^^^^^^


Mime
View raw message