Transactions

Wolfgang Schuetzelhofer edited this page Jul 31, 2017 · 4 revisions
Previous Next Table of Contents

Transaction Handling

By default every database action performed via JCypher, no matter if a Domain Query execution, the call of a unit of DSL Expressions, or a change of the domain model updating the database via the IDomainAccess interface, is performed in a discrete transaction.

Since release 2.7.0 JCypher provides a distinct transaction API. You can handcraft an arbitrary number of database actions into a single unit of work. This unit of work can then be committed or rolled back in an atomic (all or nothing) kind of way.

You start a transaction by calling beginTX() either on an IDBAccess instance (in case you work with Query DSL Expressions) or on an IDomainAccess instance (in case you work with complex domains or Domain Queries respectively).

// begin a transaction (a unit of work)
ITransaction tx = domainAccess.beginTX();

After that you can perform any number of database actions. They are performed in the context of this transaction.
Note:
Transactions are thread confined (a transaction is bound to the thread which started the transaction) and can be nested as “flat nested transactions”. Flat nested transactions means that all nested transactions are added to the scope of the top level transaction. A nested transaction can mark the top level transaction for rollback, meaning the entire transaction will be rolled back. To only rollback changes made in a nested transaction is not possible.

A transaction is closed by calling close() on the transaction. Depending on the failure or success state of the transaction it is either committed or rolled back. As long as you have never called failure() on the transaction after it was started, the transaction will stay in success state and be committed on close.
As soon as you call failure() on a transaction, it moves to failure state and will be rolled back on close. Once you have called failure() you can do nothing to bring the transaction back to success state.

// add database actions
   :

// close the transaction;
// it will be committed, because it was not marked as failed
List<JcError> errors = tx.close();

Roll back a transaction:

// begin a transaction (a unit of work)
ITransaction tx = domainAccess.beginTX();

// add database actions
   :

// mark the transaction as failed
tx.failure();

// close the transaction;
// it will be rolled back, because it was marked as failed
List<JcError> errors = tx.close();

Previous Next Table of Contents