[
https://issues.apache.org/jira/browse/TINKERPOP-3253?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18089944#comment-18089944
]
ASF GitHub Bot commented on TINKERPOP-3253:
-------------------------------------------
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436959482
##########
docs/src/reference/the-traversal.asciidoc:
##########
@@ -60,8 +60,57 @@ traversal strategies may not function properly.
image:gremlin-coins.png[width=100,float=right] A
link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
represents a unit of work to execute against the database. A traversals unit
of work is affected by usage convention
(i.e. the method of <<connecting-gremlin, connecting>>) and the graph
provider's transaction model. Without diving
-deeply into different conventions and models the most general and recommended
approach to working with transactions is
-demonstrated as follows:
+deeply into different conventions and models, the recommended way to work with
transactions is to wrap the unit of
+work in a closure passed to `executeInTx` (or `evaluateInTx` when a value must
be returned), which manages the
+transaction lifecycle for you:
+
+[source,java]
+----
+GraphTraversalSource g = traversal().with(graph);
+// or
+GraphTraversalSource g = traversal().with(conn);
+
+// the closure receives the transaction-bound gtx; the transaction is begun
+// automatically, committed when the closure completes normally, and rolled
+// back if it throws
+g.executeInTx(gtx -> {
+ gtx.addV('person').iterate();
+ gtx.addV('software').iterate();
+});
+
+// use evaluateInTx when the unit of work needs to return a value
+long count = g.evaluateInTx(gtx -> gtx.V().count().next());
+----
+
+This closure form is preferred for several reasons:
Review Comment:
I personally would like docs to steer clear of heavy reliance on bullets. A
smoothly written paragraph is the form we should try to stick to for "reasons".
The entire readable internet is leaning into bullets like this now and I think
TinkerPop is better for breaking from that. Not saying they can't ever be used,
but this just doesn't seem like content to do it with.
> Add convenience lambdas for transactions
> ----------------------------------------
>
> Key: TINKERPOP-3253
> URL: https://issues.apache.org/jira/browse/TINKERPOP-3253
> Project: TinkerPop
> Issue Type: Improvement
> Components: dotnet, driver, go, javascript, python
> Affects Versions: 4.0.0
> Reporter: Ken Hu
> Priority: Major
>
> A common usage for transactions is just to begin, do one operation and then
> commit. This currently requires three separate calls. Add some convenience
> methods that will wrap the operation in a begin() and commit().
> Originally discussed in:
> https://lists.apache.org/thread/khnz10j0ox640ch2ooq3zkpy4kmo6wxj
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
