This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 0eb52114f6 Updated tx docs a little bit in preparation for release CTR
0eb52114f6 is described below
commit 0eb52114f608a754d508efaa3297eb98c3c18e06
Author: Stephen Mallette <[email protected]>
AuthorDate: Fri Jul 28 12:01:09 2023 -0400
Updated tx docs a little bit in preparation for release CTR
---
docs/src/reference/gremlin-applications.asciidoc | 26 ------
.../reference/implementations-tinkergraph.asciidoc | 102 +++++++++++++++++----
docs/src/reference/intro.asciidoc | 2 +-
docs/src/upgrade/release-3.7.x.asciidoc | 29 +++---
4 files changed, 104 insertions(+), 55 deletions(-)
diff --git a/docs/src/reference/gremlin-applications.asciidoc
b/docs/src/reference/gremlin-applications.asciidoc
index 3b9164f076..b05999cb61 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -2578,32 +2578,6 @@ simply retry the request later. In the event a client
detects a `ResponseStatusC
which is error code `596`, the client may choose to retry that request. Note
that drivers do not have the ability to
automatically retry and that it is up to the application to provide such logic.
-[[testing-remote-providers]]
-==== Testing Remote Providers
-
-As of 3.7.0, it is recommended to use TinkerTransactionGraph, the
transactional TinkerGraph, for testing, as it provides
-transactional capabilities on top of exiting TinkerGraph functionalities.
-
-To use TinkerTransactionGraph remotely, start a Gremlin Server with the
`gremlin-server-transaction.yaml` config file.
-
-[source,java]
-----
-Cluster cluster = Cluster.build("localhost").port(8182).create();
-Client client = cluster.connect();
-GraphTraversalSource g =
traversal().withRemote(DriverRemoteConnection.using(client, "g"));
-GraphTraversalSource gtx = g.tx().begin();
-
-try {
- Vertex marko =
gtx.addV("person").property("name","marko").property("age",29).next();
- Vertex lop =
gtx.addV("software").property("name","lop").property("lang","java").next();
- gtx.addE("created").from(marko).to(lop).property("weight",0.6d).iterate();
-
- gtx.tx().commit();
-} catch (Exception ex) {
- gtx.tx().rollback();
-}
-----
-
[[gremlin-server-docker-image]]
=== Docker Image
diff --git a/docs/src/reference/implementations-tinkergraph.asciidoc
b/docs/src/reference/implementations-tinkergraph.asciidoc
index 2ddba9e28e..f0ba65f1ce 100644
--- a/docs/src/reference/implementations-tinkergraph.asciidoc
+++ b/docs/src/reference/implementations-tinkergraph.asciidoc
@@ -160,6 +160,9 @@ also be specified. If this value is not included
(default), then the graph will
loaded/persisted to disk.
|=========================================================
+NOTE: To use <<tinkergraph-gremlin-tx, transactions>>, configure
`gremlin.graph` as
+`org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerTransactionGraph`.
+
The `IdManager` settings above refer to how TinkerGraph will control
identifiers for vertices, edges and vertex
properties. There are several options for each of these settings: `ANY`,
`LONG`, `INTEGER`, `UUID`, or the fully
qualified class name of an `IdManager` implementation on the classpath. When
not specified, the default values
@@ -199,41 +202,105 @@ g.io("data/tinkerpop-crew.kryo").read().iterate()
g.V().properties()
----
+[[tinkergraph-gremlin-tx]]
=== Transactions
-As of 3.7.0, `TinkerGraph` includes optional transaction support and
thread-safety through the `TinkerTransactionGraph`
-class. The default configuration of TinkerGraph remains non-transactional.
+`TinkerGraph` includes optional transaction support and thread-safety through
the `TinkerTransactionGraph` class.
+The default configuration of TinkerGraph remains non-transactional.
+
+NOTE: This feature was first made available in TinkerPop 3.7.0.
==== Transaction Semantics
-TinkerTransactionGraph only has support for ThreadLocal transactions, so
embedded graph transactions may not be fully
+`TinkerTransactionGraph` only has support for `ThreadLocal` transactions, so
embedded graph transactions may not be fully
supported. You can think of the transaction as belonging to a thread, any
traversals executed within the same thread
will share the same transaction even if you attempt to start a new transaction.
-TinkerTransactionGraph provides the `read committed` transaction isolation
level. This means that it will always try to
+`TinkerTransactionGraph` provides the `read committed` transaction isolation
level. This means that it will always try to
guard against dirty reads. While you may notice stricter isolation semantics
in some cases, you should not depend on
this behavior as it may change in the future.
-TinkerTransactionGraph employs optimistic locking as its locking strategy.
This reduces complexity in the design as
+`TinkerTransactionGraph` employs optimistic locking as its locking strategy.
This reduces complexity in the design as
there are fewer timeouts that the user needs to manage. However, a consequence
of this approach is that a transaction
will throw a `TransactionException` if two different transactions attempt to
lock the same element (see "Best Practices"
below).
-==== Use Cases
+[[testing-remote-providers]]
+==== Testing Remote Providers
These transaction semantics described above may not fit use cases for some
production scenarios that require strict
-ACID-like transactions. Therefore, it is recommended that
TinkerTransactionGraph be used as a Graph for test
-environments where you still require access to a Graph that supports
transactions. TinkerTransactionGraph does fully
-support TinkerPop's `Transaction` interface which still makes it a useful
Graph for exploring the Transaction API.
+ACID-like transactions. Therefore, it is recommended that
`TinkerTransactionGraph` be used as a `Graph` for test
+environments where you still require access to a `Graph` that supports
transactions. `TinkerTransactionGraph` does fully
+support TinkerPop's `Transaction` interface which still makes it a useful
`Graph` for exploring the
+<<transactions,Transaction API>>.
-Once you are ready to put your system into production then you can choose a
Graph provider that has the
-transaction semantics that fit your application's needs.
+A common scenario where this sort of testing is helpful is with
<<connecting-rgp, Remote Graph Providers>>, where
+developing unit tests might be hard against a graph service. Instead,
configure `TinkerTransactionGraph`, either in an
+embedded style if using Java or with Gremlin Server for other cases.
+
+[source,java]
+----
+// consider this class that returns the results of some Gremlin. by
constructing the
+// GraphService in a way that takes a GraphTraversalSource it becomes possible
to
+// execute getPersons() under any graph system.
+public class GraphService {
+ private final GraphTraversalSource g;
+
+ public GraphService(GraphTraversalSource g) {
+ this.g = g;
+ }
+
+ public List<Vertex> getPersons() {
+ return g.V().hasLabel("person").toList();
+ }
+}
+
+// when writing tests for the GraphService it becomes possible to configure
the test
+// to run in a variety of scenarios. here we decide that
TinkerTransactionGraph is a
+// suitable test graph replacement for our actual production graph.
+public class GraphServiceTest {
+ private static final TinkerTransactionGraph graph =
TinkerTransactionGraph().open();
+ private static final GraphTraversalSource g =
traversal.withEmbedded(graph);
+ private static final GraphService service = new GraphService(g);
+
+ @Test
+ public void shouldGetPersons() {
+ final List<Vertex> persons = service.getPersons();
+ assertEquals(6, persons.size());
+ }
+}
+
+// or perhaps, since we're using a remote graph provider, we feel it would be
better to
+// start Gremlin Server with a TinkerTransactionGraph configured using a
docker container,
+// embedding it directly in our tests or running it as a separate process like:
+//
+// bin/gremlin-server.sh conf/gremlin-server-transaction.yaml
+//
+// and then connect to it with a driver in more of an integration test style.
obviously,
+// with this approach you could also configure your production graph directly
or use custom
+// build options to trigger different test configurations for a more dynamic
approach
+public class GraphServiceTest {
+ private static final GraphTraversalSource g = traversal.withRemote(
+ new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+ private static final GraphService service = new GraphService(g);
+
+ @Test
+ public void shouldGetPersons() {
+ final List<Vertex> persons = service.getPersons();
+ assertEquals(6, persons.size());
+ }
+}
+----
+
+WARNING: There can be subtle behavioral differences between TinkerGraph and
the graph ultimately intended for use.
+Be aware of the differences when writing tests to ensure that you are testing
behaviors of your applications
+appropriately.
==== Best Practices
-Errors can occur before a transaction gets committed. Specifically for
TinkerTransactionGraph, you may encounter many
-`TransactionException`s in a highly concurrent environment due its optimistic
approach to locking. Users should follow
-the try-catch-rollback pattern described in the
+Errors can occur before a transaction gets committed. Specifically for
`TinkerTransactionGraph`, you may encounter many
+`TransactionException` errors in a highly concurrent environment due its
optimistic approach to locking. Users should
+follow the try-catch-rollback pattern described in the
link:https://tinkerpop.apache.org/docs/x.y.z/reference/#transactions[transactions]
section in combination with
exponential backoff based retries to mitigate this issue.
@@ -241,17 +308,18 @@ exponential backoff based retries to mitigate this issue.
While transactions impose minimal impact for mutating workloads, users should
expect performance degradation for
read-only work relative to the non-transactional configuration. However, its
approach to locking
-(write-only, optimistic) and its in-memory nature, TinkerTransactionGraph is
likely faster than other Graph
+(write-only, optimistic) and its in-memory nature, TinkerTransactionGraph is
likely faster than other `Graph`
implementations that support transactions.
==== Examples
-Constructing a simple graph using TinkerTransactionGraph in Java is presented
below:
+Constructing a simple graph using `TinkerTransactionGraph` in Java is
presented below:
[source,java]
----
Graph graph = TinkerTransactionGraph.open();
-GraphTraversalSource gtx = graph.tx().begin();
+g = traversal().withEmbedded(graph)
+GraphTraversalSource gtx = g.tx().begin();
try {
Vertex marko =
gtx.addV("person").property("name","marko").property("age",29).next();
diff --git a/docs/src/reference/intro.asciidoc
b/docs/src/reference/intro.asciidoc
index 7697cbc75a..4a85ede578 100644
--- a/docs/src/reference/intro.asciidoc
+++ b/docs/src/reference/intro.asciidoc
@@ -477,7 +477,7 @@ the <<connecting-gremlin-server,previous section>> with the
exact same caveats p
Despite leveraging TinkerPop protocols and drivers as being typical, RGPs are
not required to do so to be considered
TinkerPop-enabled. RGPs may well have their own drivers and protocols that may
plug into
-<<gremlin-drivers-variants,Gremlin Language Variants> and may allow for more
advanced options like better security,
+<<gremlin-drivers-variants,Gremlin Language Variants>> and may allow for more
advanced options like better security,
cluster awareness, batched requests or other features. The details of these
different systems are outside the scope
of this documentation, so be sure to consult their documentation for more
information.
diff --git a/docs/src/upgrade/release-3.7.x.asciidoc
b/docs/src/upgrade/release-3.7.x.asciidoc
index 59811f5270..b9c7bdc925 100644
--- a/docs/src/upgrade/release-3.7.x.asciidoc
+++ b/docs/src/upgrade/release-3.7.x.asciidoc
@@ -162,15 +162,13 @@ See:
link:https://issues.apache.org/jira/browse/TINKERPOP-2957[TINKERPOP-2957]
==== TinkerGraph Transactions
-===== Introduction
-
Previously, there was no reference implementation provided for the
`Transaction` API as this feature wasn't supported by
TinkerGraph. Users were instead directed towards the Neo4jGraph provided in
`neo4j-gremlin` if they wanted to get access
to a `Graph` implementation that supported transactions. Unfortunately, the
maintenance around this plugin has largely
been abandoned and is only compatible with Neo4j version 3.4, which reached
end of life in March 2020.
-As of this version, we are introducing the transactional TinkerGraph,
TinkerTransactionGraph, which is TinkerGraph with
-transaction capabilities. The TinkerTransactionGraph has `read committed`
isolation level, which is the same as the
+As of this version, we are introducing the transactional TinkerGraph,
`TinkerTransactionGraph`, which is TinkerGraph with
+transaction capabilities. The `TinkerTransactionGraph` has `read committed`
isolation level, which is the same as the
Neo4jGraph provided in `neo4j-gremlin`. Only `ThreadLocal` transactions are
implemented, therefore embedded graph
transactions may not be fully supported. These transaction semantics may not
fit the use case for some production
scenarios that require strict ACID-like transactions. Therefore, it is
recommended that TinkerTransactionGraph be used
@@ -178,7 +176,15 @@ as a Graph for test environments where you still require
support for transaction
===== Usage examples
-To use TinkerTransactionGraph remotely, start a Gremlin Server with the
`gremlin-server-transaction.yaml` config file.
+To use `TinkerTransactionGraph` remotely, start a Gremlin Server with the
included `gremlin-server-transaction.yaml`
+config file.
+
+[source,bash]
+----
+bin/gremlin-server.sh conf/gremlin-server-transaction.yaml
+----
+
+Then to connect with Java:
[source,java]
----
@@ -274,14 +280,15 @@ gremlin> g.V().valueMap()
<4> Add a second vertex without committing
<5> Rollback the change
-Note that all embedded TinkerTransactionGraph remains ThreadLocal
transactions, meaning that all traversal sources spawn
-from the graph will operate within the same transaction scope.
+Note that all embedded `TinkerTransactionGraph` remains `ThreadLocal`
transactions, meaning that all traversal sources
+spawned from the graph will operate within the same transaction scope.
-===== Limitations
-At this point, the transactional TinkerGraph comes with performance
limitations and thus is only meant for testing
-and not for production use.
+IMPORTANT: `TinkerTransactionGraph` comes with performance and semantic
limitations, where the former is expect to
+be resolved in future versions. Since its primary recommended use case is for
testing these limitations should not be
+an impediment. Production use cases for TinkerGraph should generally prefer
the non-transactional implementation.
-Addition documentation can be found in <<transactions,Transactions>> section.
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2975[TINKERPOP-2975],
+link:https://tinkerpop.apache.org/docs/3.7.0/reference/#tinkergraph-gremlin-tx[Reference
Documentation - TinkerGraph Transactions]
==== Properties on Elements
