Added a doc for future TinkerPop development CTR
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/bb108cce Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/bb108cce Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/bb108cce Branch: refs/heads/TINKERPOP-1427 Commit: bb108cceadcd76851b162a6abbfd17a3f5ef4417 Parents: 31f8752 Author: Stephen Mallette <[email protected]> Authored: Thu Jul 13 12:13:36 2017 -0400 Committer: Stephen Mallette <[email protected]> Committed: Thu Jul 13 12:13:36 2017 -0400 ---------------------------------------------------------------------- docs/src/dev/future/index.asciidoc | 106 +++++++++++++++++++++++++++ docs/static/images/rexster-milkbone.png | Bin 0 -> 104534 bytes docs/static/images/tp4-think.png | Bin 0 -> 482790 bytes pom.xml | 25 +++++++ 4 files changed, 131 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/bb108cce/docs/src/dev/future/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/future/index.asciidoc b/docs/src/dev/future/index.asciidoc new file mode 100644 index 0000000..ea115e7 --- /dev/null +++ b/docs/src/dev/future/index.asciidoc @@ -0,0 +1,106 @@ +//// +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. +//// +image::apache-tinkerpop-logo.png[width=500,link="http://tinkerpop.apache.org";] + +*4.0.0* + +:toc-position: left + +TinkerPop 4.x Design Ideas +========================== + +TinkerPop 4.x is not a version considered on the immediate horizon, but there are often points in the day to day +development of TinkerPop 3.x where there are changes of importance, novelty and usefulness that are so big that they +could only be implemented under a major new version. This document is meant to track these concepts as they develop, +so that at some point in the future they can be referenced in a single place. + +There is no particular layout or style to this document. Simple bullet points, open questions posed as single +sentences, or fully structured document headers and content are all acceptable. The main point is to capture ideas +for future consideration when 4.x becomes the agenda of the day for The TinkerPop. + +image:tp4-think.png[] + +Hiding Blueprints +----------------- + +Originally from the link:https://lists.apache.org/thread.html/b4d80072ad36849b4e9cd3308f87115660574e3e7a4abb7ee68e959b@%3Cdev.tinkerpop.apache.org%3E[mailing list]: + +Throughout our documentation we show uses of the âBlueprints APIâ (i.e. Graph/Vertex/Edge/etc. classes & methods) as +well as the use of the Traversal API (i.e. Gremlin). + +Enabling users to have two ways of interacting with the graph system has its problems: + +1. The DetachedXXX problem â how much data should a returned vertex/edge/etc. have associated with it? +2. `graph.addVertex()` and `g.addV()` â which should I use? The first is faster but is not recommended. +3. `SubgraphStrategy` leaking â I get subgraphs with Gremlin, but can then directly interact with the vertex objects to see more than I should. +4. `VertexProgram` model â I write traversals with Traversal API, but then develop VertexPrograms with the Blueprints API. Thatâs weird. +5. GremlinServer returning fat objects â Serializers are created property-rich vertices and edges. The awkward HaltedTraversalStrategy solution. +6. ⦠various permutations of these source problems. + +In TinkerPop4 the solution might be as follows: + +There should be two âGraph APIs.â + +1. Provider Graph API: This is the current Blueprints API with `Graph.addVertex()`, `Vertex.edges()`, `Edge.inVertex()`, etc. +2. User Graph API: This is a ReferenceXXX API. + +The first API is well known, but the second bears further discussion. `ReferenceGraph` is simply a reference/dummy/proxy +to the provider Graph API. `ReferenceGraph` has the following API: + +* `ReferenceGraph.open()` +* `ReferenceGraph.close()` +* `ReferenceGraph.tx()` // assuming we like the current transaction model (??) +* `ReferenceGraph.traversal()` + +That is it. What does this entail? Assume the following traversal: + +[source,java] +---- +g = ReferenceGraph.open(config).traversal() +g.V(1).out(âknowsâ) +---- + +`ReferenceGraph` is almost like a `RemoteGraph` (`RemoteStrategy`) in that it makes a connection (remote or inter-JVM) +to the provider Graph API. When `g.V(1).out(âknowsâ)` executes, it is really sending the bytecode to the provider Graph +for execution (as specified by the config of `ReferenceGraph.open()`). Thus, once it hits the provider's graph, +`ProviderVertex`, `ProviderEdge`, etc. are the objects being processed. However, what the traversalâs `Iterator<Vertex>` +returns is `ReferenceVertex`! That is, it never returns `ProviderVertex`. In this way, regardless if the user is +going âover the wireâ or within the same JVM or against a different providerâs graph database or from +Gremlin-Python/C#/etc., all the vertices are simply âreference verticesâ (id + label). This makes it so that users +never interact with the graph element objects themselves directly. They can ONLY interact with the graph via +traversals! At most they can `ReferenceVertex.id()` and `ReferenceVertex.label()`. Thats it, â no mutations, not +walking edges, nada! And moreover, since ReferenceXXX has enough information to re-attach to the source graph, they +can always do the following to get more information: + +[source,java] +---- +v = g.V(1).out(âknowsâ).next() +g.V(v).values(ânameâ) +---- + +This split into two Graph APIs will enables us to make a hard boundary between what the provider (vendor) needs to +implement and what the user (developer) gets to access. + +Comments +~~~~~~~~ + +There is a question mark next to `ReferenceGraph.tx()` - Transactions are a bit of an open question for future versions +of TinkerPop and likely deserve their own section in this document. The model used for last three version of TinkerPop +now is rooted in the Neo4j approach to transactions and is often more trouble than it should be for us and providers. +Distributed transactions are a challenge and don't apply to every provider. Transactions are further complicated by +GLVs. The idea of local subgraphs for mutations and transaction management might be good but that goes against having +just `ReferenceGraph`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/bb108cce/docs/static/images/rexster-milkbone.png ---------------------------------------------------------------------- diff --git a/docs/static/images/rexster-milkbone.png b/docs/static/images/rexster-milkbone.png new file mode 100644 index 0000000..c1077d3 Binary files /dev/null and b/docs/static/images/rexster-milkbone.png differ http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/bb108cce/docs/static/images/tp4-think.png ---------------------------------------------------------------------- diff --git a/docs/static/images/tp4-think.png b/docs/static/images/tp4-think.png new file mode 100755 index 0000000..ea41a4b Binary files /dev/null and b/docs/static/images/tp4-think.png differ http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/bb108cce/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index c60254a..60c7e8d 100644 --- a/pom.xml +++ b/pom.xml @@ -899,6 +899,31 @@ limitations under the License. </configuration> </execution> <execution> + <id>future-book</id> + <phase>generate-resources</phase> + <goals> + <goal>process-asciidoc</goal> + </goals> + <configuration> + <sourceDirectory>${asciidoc.input.dir}/dev/future</sourceDirectory> + <sourceDocumentName>index.asciidoc</sourceDocumentName> + <outputDirectory>${htmlsingle.output.dir}/dev/future</outputDirectory> + <backend>html5</backend> + <doctype>book</doctype> + <attributes> + <imagesdir>../../images</imagesdir> + <encoding>UTF-8</encoding> + <toc>true</toc> + <toclevels>3</toclevels> + <toc-position>left</toc-position> + <stylesdir>${asciidoctor.style.dir}</stylesdir> + <stylesheet>tinkerpop.css</stylesheet> + <source-highlighter>coderay</source-highlighter> + <basedir>${project.basedir}</basedir> + </attributes> + </configuration> + </execution> + <execution> <id>io-book</id> <phase>generate-resources</phase> <goals>
