You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2017/07/21 10:44:20 UTC
tinkerpop git commit: Improved upgrade docs around IO CTR
Repository: tinkerpop
Updated Branches:
refs/heads/master 89b35b31c -> 2116819c8
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/master
Commit: 2116819c8ff111e80eff937a6ccab1a62d9786d6
Parents: 89b35b3
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Fri Jul 21 06:43:57 2017 -0400
Committer: Stephen Mallette <sp...@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
^^^^^^^^^^^^^^^^^^^^