Working with Local Transactions
Local Transactions allow single-phase commit across multiple cache operations, across one or more caches, and in the same CacheManager.This lets you apply multiple changes to a CacheManager all in your own transaction. If you also want to apply changes to other resources, such as a database, open a transaction to them and manually handle commit and rollback to ensure consistency.
Local transactions are not controlled by a transaction manager. Instead there is an explicit API where a reference is obtained to a TransactionController for the CacheManager using cacheManager.getTransactionController() and the steps in the transaction are called explicitly. The steps in a local transaction are:
transactionController.begin() - This marks the beginning of the local transaction on the current thread. The changes are not visible to other threads or to other transactions.
transactionController.commit() - Commits work done in the current transaction on the calling thread.
transactionController.rollback() - Rolls back work done in the current transaction on the calling thread. The changes done since begin are not applied to the cache. These steps should be placed in a try-catch block which catches TransactionException. If any exceptions are thrown, rollback() should be called. Local Transactions has its own exceptions that can be thrown, which are all subclasses of CacheException. They are:
TransactionException - a general exception
TransactionInterruptedException - if Thread.interrupt() was called while the cache was processing a transaction.
TransactionTimeoutException - if a cache operation or commit is called after the transaction timeout has elapsed.
Introductory Video
Ludovic Orban, the primary author of Local Transactions, presents an
introductory video on Local Transactions.
Configuration
Local transactions are configured as follows:
<cache name="sampleCache"
...
transactionalMode="local"
</cache>
Isolation Level
As with the other transaction modes, the isolation level is READ_COMMITTED.
Transaction Timeouts
If a transaction cannot complete within the timeout period, a TransactionTimeoutException is thrown. To return the cache to a consistent state, call transactionController.rollback(). Because TransactionController is at the level of the CacheManager, a default timeout can be set which applies to all transactions across all caches in a CacheManager. The default is 15 seconds. To change the defaultTimeout:
transactionController.setDefaultTransactionTimeout(int defaultTransactionTimeoutSeconds)
The countdown starts when begin() is called. You might have another local transaction on a JDBC connection and you might be making multiple changes. If you think it might take longer than 15 seconds for an individual transaction, you can override the default when you begin the transaction with:
transactionController.begin(int transactionTimeoutSeconds) {
Sample Code
The following example shows a transaction that performs multiple operations across two caches.
CacheManager cacheManager = CacheManager.getInstance();
try {
cacheManager.getTransactionController().begin();
cache1.put(new Element(1, "one"));
cache2.put(new Element(2, "two"));
cache1.remove(4);
cacheManager.getTransactionController().commit();
} catch (CacheException e) {
cacheManager.getTransactionController().rollback()
}