Transactions

Typical business logic scenarios use a single database transaction. When the client code calls a workflow rule, the latter may perform one or several data access operations. The basic assumption is that either all of these operations must succeed, or no database changes at all must be allowed to persist.

To implement this, all data access operations performed by an event-handler method (using any number of data sources) are executed within a single database transaction context. Web Central creates the transaction before calling the service, and commits (or rolls back, if the event-handler method throws an exception) the transaction after the service call is complete.

If required, the event-handler method can commit the current transaction using either the DataSource.commit() or the SqlUtils.commit() methods. All data access operations executed after this call will use a new transaction context.

The DataSource can also be set to auto-commit every database operation:

ds.setAutoCommit(true);
ds.saveRecord(record1);
ds.saveRecord(record2);

Auto-commit should be used with caution. In the example above, if save fails for the second record, there is no way to roll back the previous save for the first record. Since database failures are rare, there is a great chance that errors like this will not be detected during development – but they may still happen in production.

If any error is encountered, to force a rollback for the current transaction the service code can simply throw an exception. In scenarios where the WFR has determined that the current transaction cannot succeed (i.e. because of the concurrent data update), but has a way to fall back (i.e. by writing a record to the log table, to be executed later by a scheduled WFR) it can use the DataSource.rollback() or the SqlUtils.rollback() methods to explicitly force the rollback.