Savepoints

Savepoints allow the partial rollback of a transaction, and they operate only within the scope of a transaction.

As an example, think of a transaction as a sequence of operations over time, such as A to M, at the end of which (after M), the transaction is completed by either committing all the operations A through M or rolling them all back. It is possible to set a savepoint after a particular operation, say C. As long as the transaction is not complete, you can roll back to the savepoint. This feature preserves the operations up to and including C, and also nullifies the subsequent operations. It is possible to define a series of savepoints in this manner and roll back to any one of them, which preserves the savepoint that is rolled back to but removes all subsequent savepoints.

If you roll back to a savepoint, it is possible to continue the transaction with more operations, and to set new savepoints and roll back to any defined savepoint. When the transaction is completed, all savepoints are removed. In effect, setting a savepoint preserves the state of a transaction then (including the definition of the savepoint), and rolling back to a savepoint restores the transaction to the corresponding state.

Savepoints are implemented in two methods that are added to the Java™ API's Context interface; they are Context.setSavepoint() and Context.rollbackToSavepoint(name). The former sets a savepoint for the most recent operation (C, in the example previously) and returns a unique name as a String. The latter rolls back to the savepoint indicated by the given name. Both might be called only within an active transaction, and related calls must be within the same transaction. The precise specifications of these methods are included in the documentation of the Java API.