Added CHANGELOG entry and 'reference' docs.
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/7546bc79 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/7546bc79 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/7546bc79 Branch: refs/heads/TINKERPOP-1274 Commit: 7546bc79e8674cdeb6344e5ec96ff2cfa2c78fb8 Parents: 6cee526 Author: Kevin Gallardo <[email protected]> Authored: Wed Jun 29 18:25:45 2016 +0100 Committer: Kevin Gallardo <[email protected]> Committed: Thu Jun 30 10:41:34 2016 +0100 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 1 + docs/src/reference/the-graph.asciidoc | 135 ++++++++++++++++++++++++++++- 2 files changed, 132 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/7546bc79/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 94bb67e..5c1148b 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -26,6 +26,7 @@ image::https://raw.githubusercontent.com/apache/incubator-tinkerpop/master/docs/ TinkerPop 3.2.1 (NOT OFFICIALLY RELEASED YET) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Introduced GraphSON 2.0. * `TraversalExplanation.prettyPrint()` exists which provides word wrapping and GremlinConsole is smart to use console width to control `toString()`. * `TraversalOpProcessor` (`RemoteConnection`) uses `HaltedTraverserStrategy` metadata to determine detachment procedure prior to returning results. * Allow DFS paths in `HADOOP_GREMLIN_LIBS`. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/7546bc79/docs/src/reference/the-graph.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-graph.asciidoc b/docs/src/reference/the-graph.asciidoc index 8b4916a..9817ce8 100644 --- a/docs/src/reference/the-graph.asciidoc +++ b/docs/src/reference/the-graph.asciidoc @@ -1,4 +1,4 @@ -//// +*//// 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. @@ -13,7 +13,7 @@ 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. -//// +_//// [[graph]] The Graph ========= @@ -499,7 +499,7 @@ graph.io(graphson()).writer().create().writeVertex(f, g.V(1).next(), BOTH) f.close() ---- -The following GraphSON example shows the output of `GraphSonWriter.writeVertex()` with associated edges: +The following GraphSON example shows the output of `GraphSONWriter.writeVertex()` with associated edges: [source,json] ---- @@ -553,7 +553,18 @@ The following GraphSON example shows the output of `GraphSonWriter.writeVertex() The vertex properly serializes to valid JSON but note that a consuming application will not automatically know how to interpret the numeric values. In coercing those Java values to JSON, such information is lost. -With a minor change to the construction of the `GraphSONWriter` the lossy nature of GraphSON can be avoided: +[[graphson-types-embedding]] +Types embedding +^^^^^^^^^^^^^^^ + +With a minor change to the construction of the `GraphSONWriter` the lossy nature of GraphSON can be avoided. + +[[graphson-1.0-types]] +Types with GraphSON 1.0. +++++++++++++++++++++++++ + +GraphSON 1.0 is the version enabled by default when creating a GraphSON Mapper. Here is how to enable types with GraphSON +1.0: [gremlin-groovy] ---- @@ -652,6 +663,121 @@ from JSON typing. While the output is more verbose, it comes with the security non-JVM languages won't be able to consume this information automatically, at least there is a hint as to how the values should be coerced back into the correct types in the target language. +[[graphson-2.0-types]] +GraphSON 2.0. ++++++++++++++ + +GraphSON 2.0 has been introduced to improve the format of the typed values from GraphSON 1.0. It provides non-Java +centric types information in a consistent format. With GraphSON 2.0, types are enabled by default. As for GraphSON 1.0 +types will not be included for JSON's "natural" types (String, Boolean, Integer, and Double). + +The format is : + +* Non typed value : `value` +* Typed value : `[{"@class":"typeName"}, value]` + +Here's the same previous example, but with GraphSON 2.0: + +[gremlin-groovy] +---- +graph = TinkerFactory.createModern() +g = graph.traversal() +f = new FileOutputStream("vertex-2.json") +mapper = graph.io(graphson()).mapper().version(GraphSONVersion.V2_0).create() +v = g.V(1).next() +v.property("uuid", UUID.randomUUID()) +graph.io(graphson()).writer().mapper(mapper).create().writeVertex(f, v, BOTH) +f.close() +---- + +Creating a GraphSON 2.0 mapper is done by calling `.version(GraphSONVersion.V2_0)` on the mapper builder. For this +example the serialized `Vertex` is added a property that is not a JSON natural value in order to demonstrate the format: + +[source,json] +---- +{ + "id":1, + "label":"person", + "outE":{ + "created":[ + { + "id":9, + "inV":3, + "properties":{ + "weight":0.4 + } + } + ], + "knows":[ + { + "id":7, + "inV":2, + "properties":{ + "weight":0.5 + } + }, + { + "id":8, + "inV":4, + "properties":{ + "weight":1.0 + } + } + ] + }, + "properties":{ + "name":[ + { + "id":[ + { + "@class":"Long" + }, + 0 + ], + "value":"marko" + } + ], + "uuid":[ + { + "id":[ + { + "@class":"Long" + }, + 12 + ], + "value":[ + { + "@class":"UUID" + }, + "1de7bedf-f9ba-4e94-bde9-f1be28bef239" + ] + } + ], + "age":[ + { + "id":[ + { + "@class":"Long" + }, + 1 + ], + "value":29 + } + ] + } +} +---- + +The only values that have a type are the ones that are non JSON native. + +Types can be explicitly disabled, in that case the JSON produced will be the same than GraphSON 1.0 without types. +Here's how to disable types with GraphSON 2.0: + +[gremlin-groovy] +---- +mapper = graph.io(graphson()).mapper().version(GraphSONVersion.V2_0).typeInfo(GraphSONMapper.TypeInfo.NO_TYPES).create() +---- + [[gryo-reader-writer]] Gryo Reader/Writer ~~~~~~~~~~~~~~~~~~ @@ -773,3 +899,4 @@ reduce implementations, and plugins. The only truly protected namespace is the _hidden namespace_ provided to graph systems. From there, it's up to engineers to respect the namespacing conventions presented. +*_ \ No newline at end of file
