Graph Transactions

A Graph that implements the TransactionalGraph or ThreadedTransactionalGraph interfaces must natively support transaction handling. A transaction describes a coherent and complete unit of work comprised of multiple read and write operations to be executed against the database together or not at all. In addition, transactions are needed to handle conflicts and consistency issues that arise when multiple users interact with the Graph concurrently. The exact ACID and isolation level guarantees extended by a TransactionalGraph or ThreadedTransactionalGraph depend on the specific implementation.

TransactionalGraph and Starting and Stopping Transactions

A TransactionalGraph has just one method for terminating the transaction:

public void stopTransaction(Conclusion conclusion);

Transactions are automatically started with the first operation on the graph, that is, any read or write operation. Transactions need to be manually closed to mark the end of a transactional context and to inform the graph database whether the transaction was successful or not, by passing Conclusion.SUCCESS or Conclusion.FAILURE to stopTransaction, respectively.

Transactions are bound to the current thread, which means that any graph operation executed by the thread occurs in the context of that transaction and that there may only be one thread executing in a single transaction. For thread independent transactions that allow concurrent thread access, use ThreadedTransactionalGraph.

When a transaction is started, all the subsequent read and write operations occur within this transaction context. When the transaction is successfully stopped, those mutations operations are persisted and visible to other contexts interacting with the graph and all locks are released. If a transaction is failed, then the mutation operations are “rolled back” to when the transaction was started.
TransactionalGraph makes no assumptions about how transactions are implemented by a graph database. Hence, a transaction may fail at any point if a conflict arises that could not be resolved.

Note, that a TransactionalGraph.shutdown() will automatically successfully commit any open transaction. Also note, that keeping transactions open for a long time may result in OutOfMemoryException if too many mutations have occurred and possible dead-locks if locks are held for too long in multi-user environments.

Note, that element references created in a transactional context may not be accessed outside the transactional context. Doing so may cause an exception. A transaction marks a complete unit of work and after it is stopped, its state may be discarded. Moreover, concurrently running transaction can render such references out-of-sync. Any references created during the transaction may therefore no longer be alive. Hence, the following code snippet may cause an exception:

Vertex v = graph.addVertex(null);
//More operations inside the transaction
stopTransaction(Conclusion.SUCCESS);
//Other code
v.setProperty("name","marko");

In such cases, the transactional context should be extended until all operations have been completed. In other words, the stopTransaction(Conclusion.SUCCESS) call should be moved after the v.setProperty("name","marko"); write operation.
In cases where the element reference needs to be accessed outside its original transactional context, it should be re-instantiated based on the element id. For example:

Vertex v = graph.addVertex(null);
//More operations inside the transaction
stopTransaction(Conclusion.SUCCESS);
//Other code
startTransaction();
v = graph.getVertex(v.getId());
v.setProperty("name","marko");

ThreadedTransactionalGraph and Multi-Threads for One Transaction

ThreadedTransactionalGraph provides more fine grained control over the transactional context.
While TransactionalGraph binds each transaction to the executing thread, ThreadedTransactionalGraph.startTransaction() returns a TransactionalGraph that represents its own transactional context independent of the executing thread.
Hence, one can have multiple threads operating against a single transaction represented by the returned TransactionalGraph object. This is useful for parallelizing graph algorithms.

A ThreadedTransactionalGraph extends TransactionalGraph with a single method.

public TransactionalGraph startTransaction()

The returned transaction represented by a TransactionalGraph object needs to be explicitly closed by calling TransactionalGraph.stopTransaction(Conclusion conclusion). Calling TransactionalGraph.shutdown() will successfully commit the transaction without closing the underlying graph database.