org.neo4j.graphdb
Interface Transaction

All Known Implementing Classes:

PlaceboTransaction, TopLevelTransaction

public interface Transaction

A programmatically handled transaction. All modifying operations that work with the node space must be wrapped in a transaction. Transactions are thread confined. Transactions can either be handled programmatically, through this interface, or by a container through the Java Transaction API (JTA). The Transaction interface makes handling programmatic transactions easier than using JTA programmatically. Here's the idiomatic use of programmatic transactions in Neo4j:

 
 Transaction tx = graphDb.beginTx();
 try
 {
        ... // any operation that works with the node space
     tx.success();
 }
 finally
 {
     tx.finish();
 }
 
 

Let's walk through this example line by line. First we retrieve a Transaction object by invoking the GraphDatabaseService.beginTx() factory method. This creates a new Transaction instance which has internal state to keep track of whether the current transaction is successful. Then we wrap all operations that work with the node space in a try-finally block. At the end of the block, we invoke the tx.success() method to indicate that the transaction is successful. As we exit the block, the finally clause will kick in and tx.finish will commit the transaction if the internal state indicates success or else mark it for rollback.

If an exception is raised in the try-block, success() will never be invoked and the internal state of the transaction object will cause finish() to roll back the transaction. This is very important: unless success() is invoked, the transaction will fail upon finish(). A transaction can be explicitly marked for rollback by invoking the failure() method.

Read operations inside of a transaction will also read uncommitted data from the same transaction.

Method Summary

Lock	acquireReadLock(PropertyContainer entity) Acquires a read lock for entity for this transaction.
Lock	acquireWriteLock(PropertyContainer entity) Acquires a write lock for entity for this transaction.
void	failure() Marks this transaction as failed, which means that it will unconditionally be rolled back when finish() is called.
void	finish() Commits or marks this transaction for rollback, depending on whether success() or failure() has been previously invoked.
void	success() Marks this transaction as successful, which means that it will be committed upon invocation of finish() unless failure() has or will be invoked before then.

Method Detail

failure

void failure()

Marks this transaction as failed, which means that it will unconditionally be rolled back when finish() is called. Once this method has been invoked, it doesn't matter if success() is invoked afterwards -- the transaction will still be rolled back.

success

void success()

Marks this transaction as successful, which means that it will be committed upon invocation of finish() unless failure() has or will be invoked before then.

finish

void finish()

Commits or marks this transaction for rollback, depending on whether success() or failure() has been previously invoked.

acquireWriteLock

Lock acquireWriteLock(PropertyContainer entity)

Acquires a write lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.

Parameters:

entity - the entity to acquire a lock for. If another transaction currently holds a write lock to that entity this call will wait until it's released.

Returns:

a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released with the transaction finishes.

acquireReadLock

Lock acquireReadLock(PropertyContainer entity)

Acquires a read lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.

Parameters:

entity - the entity to acquire a lock for. If another transaction currently hold a write lock to that entity this call will wait until it's released.

Returns:

a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released with the transaction finishes.