Graph Transactions

A Graph that implements the TransactionalGraph interface is a graph that supports Blueprints-style transactions. A TransactionalGraph has the following methods:

public void setTransactionBuffer(int bufferSize);
public int getTransactionBuffer();
public void startTransaction();
public void stopTransaction(Conclusion conclusion);

Automatic Transactions

A TransactionalGraph supports a transactional buffer. When the buffer size is greater than 0, every X manipulations of the graph (e.g. set/remove property, add/remove vertex, add/remove edge) is automatically wrapped in a transaction and committed, where X is the transaction buffer size. In this way, the developer does not need to start and stop transactions as this is automatically handled by the implementation. Upon construction, every TransactionalGraph has a transaction buffer size of 1. When the transaction buffer size is 0, the developer is required to manually start and stop transactions when editing the graph.

Transaction Examples

To put a graph in manual transaction model, evaluate the following:

txGraph.setTransactionBuffer(0);

Upon doing so, any edit operation (or group of edit operations) must be wrapped in a transaction. This is done as follows.

txGraph.startTransaction();
// edit operations
tx.stopTransaction(TransactionalGraph.Conclusion.SUCCESS);

There are two types of conclusions: Conclusion.SUCCESS and Conclusion.FAILURE. When a transaction is successful, it is committed to the underlying store. When the transaction is a failure, then all the edit operations up to the start of the transaction are rolled back. Note: Blueprints-enabled graphs do not require transactions for read-based operations.

Finally, the relationship between automatic and manual transactions are explained with an example:

The @CommitManager@ class can be instantiated using @TransactionalGraphHelper.createCommitManager()@. A @CommitManager@ is useful when inserting large amounts of data into a @TransactionalGraph@. For example, a pattern that looks like this:

When doing batch mutations using manual transactions, the code looks as follows:

```java
int counter = 0;
txGraph.setTransactionBuffer(0);
txGraph.startTransaction();

while(doingStuff) {
  // do a graph manipulation
  counter++;
  if(counter % 1000 == 0) {
    System.out.print(".");
    txGraph.stopTransaction(Conclusion.SUCCESS);
    txGraph.startTransaction();
  }
}
txGraph.stopTransaction(Conclusion.SUCCESS);

This code, using automatic transaction handling can be simplified with a transaction buffer size of 1000.

txGraph.setTransactionBuffer(1000);
while(doingStuff) {
  // do a graph manipulation
}