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. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
