org.neo4j.driver.v1

Interface Transaction

All Superinterfaces:

AutoCloseable, Resource, StatementRunner

public interface Transaction
extends Resource, StatementRunner

Logical container for an atomic unit of work. A driver Transaction object corresponds to a server transaction.

Blocking API:

Transactions are typically wrapped in a try-with-resources block which ensures that COMMIT or ROLLBACK occurs correctly on close. Note that ROLLBACK is the default action unless success() is called before closing.

 try(Transaction tx = session.beginTransaction())
 {
     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
     tx.success();
 }
 
 

Blocking calls are: success(), failure(), close() and various overloads of StatementRunner.run(Statement).

Asynchronous API:

Transactions are typically obtained in a CompletionStage and all operations chain on this stage. Explicit commit with commitAsync() or rollback with rollbackAsync() is required. Without explicit commit/rollback corresponding transaction will remain open in the database.

 
 session.beginTransactionAsync()
        .thenCompose(tx ->
               tx.runAsync("CREATE (a:Person {name: {x}})", parameters("x", "Alice"))
                 .exceptionally(e -> {
                    e.printStackTrace();
                    return null;
                 })
                 .thenApply(ignore -> tx)
        ).thenCompose(Transaction::commitAsync);
 
 

Async calls are: commitAsync(), rollbackAsync() and various overloads of StatementRunner.runAsync(Statement).

Since:

1.0

See Also:

StatementRunner.run(java.lang.String, org.neo4j.driver.v1.Value), StatementRunner

Method Summary

Modifier and Type	Method and Description
void	close() Closing the transaction will complete it - it will commit if success() has been called.
CompletionStage<Void>	commitAsync() Commit this transaction in asynchronous fashion.
void	failure() Mark this transaction as failed.
CompletionStage<Void>	rollbackAsync() Rollback this transaction in asynchronous fashion.
void	success() Mark this transaction as successful.

Methods inherited from interface org.neo4j.driver.v1.util.Resource

isOpen

Methods inherited from interface org.neo4j.driver.v1.StatementRunner

run, run, run, run, run, runAsync, runAsync, runAsync, runAsync, runAsync, typeSystem

Method Detail

success

void success()

Mark this transaction as successful. You must call this method before calling close() to have your transaction committed.

failure

void failure()

Mark this transaction as failed. When you call close(), the transaction will value rolled back. After this method has been called, there is nothing that can be done to "un-mark" it. This is a safety feature to make sure no other code calls success() and makes a transaction commit that was meant to be rolled back. Example:

 try(Transaction tx = session.beginTransaction() )
 {
     tx.run("CREATE (a:Person {name: {x}})", parameters("x", "Alice"));
     tx.failure();
 }
 
 

close

void close()

Closing the transaction will complete it - it will commit if success() has been called. When this method returns, all outstanding statements in the transaction are guaranteed to have completed, meaning any writes you performed are guaranteed to be durably stored.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Resource

commitAsync

CompletionStage<Void> commitAsync()

Commit this transaction in asynchronous fashion. This operation is typically executed as part of the CompletionStage chain that starts with a transaction. It is logically equivalent to a combination of blocking success() and close(). However, it is asynchronous and returns new CompletionStage. There is no need to close transaction after calling this method. Transaction object should not be used after calling this method.

Returned stage can be completed by an IO thread which should never block. Otherwise IO operations on this and potentially other network connections might deadlock. Please do not chain blocking operations like StatementRunner.run(String) on the returned stage. Driver will throw IllegalStateException when blocking API call is executed in IO thread. Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor. This can be done using methods with "Async" suffix like CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).

Returns:

new CompletionStage that gets completed with null when commit is successful. Stage can be completed exceptionally when commit fails.

rollbackAsync

CompletionStage<Void> rollbackAsync()

Rollback this transaction in asynchronous fashion. This operation is typically executed as part of the CompletionStage chain that starts with a transaction. It is logically equivalent to a combination of blocking failure() and close(). However, it is asynchronous and returns new CompletionStage. There is no need to close transaction after calling this method. Transaction object should not be used after calling this method.

Returned stage can be completed by an IO thread which should never block. Otherwise IO operations on this and potentially other network connections might deadlock. Please do not chain blocking operations like StatementRunner.run(String) on the returned stage. Driver will throw IllegalStateException when blocking API call is executed in IO thread. Consider using asynchronous calls throughout the chain or offloading blocking operation to a different Executor. This can be done using methods with "Async" suffix like CompletionStage.thenApplyAsync(Function) or CompletionStage.thenApplyAsync(Function, Executor).

Returns:

new CompletionStage that gets completed with null when rollback is successful. Stage can be completed exceptionally when rollback fails.