Transaction Controller
Transactions are managed through a TransactionController instance. There are two createTransactionController factory methods to create instances:
TransactionController transactionController =
TransactionController.createTransactionController // 1
(datasetManager, // 2
datasetConfigurationBuilder); // 3
1 | A TransactionController instance is required to create and execute transactions. |
2 | A DatasetManager is needed to host the internal transaction dataset. |
3 | A DatasetConfigurationBuilder is used to configure this internal transaction dataset if it does not already exist. |
If the transaction controller has already been created (and the internal transaction dataset already exists):
TransactionController controller1 =
TransactionController.createTransactionController(datasetManager); // 1
1 | A DatasetManager instance is required to load the internal transaction dataset that stores the existing metadata. |
If the internal transaction dataset does not exist and the second form is used then a DatasetMissingException will be thrown.
Once retrieved, a TransactionController instance can be used to execute actions transactionally using one of the TransactionController.execute(…) methods or a transactional execution context can be built using the TransactionController.transact() method.
Note:
If a transaction is executed against a persistent dataset, then the internal transaction dataset should also be configured as persistent since transaction metadata is stored in both the datasets involved in the transaction and the internal transaction dataset. Failure to persist either set of metadata may leave transactions in an unexpected state after a restart.
Warning:
The contents of the internal transaction dataset must not be accessed or modified by the user.
Transaction timeouts
Every transaction has a timeout defined. If a transaction does not finish before it times out, it will get rolled back by the system. Any interaction with a transaction can throw an unchecked StoreTransactionTimeOutException if the transaction has timed out.
A TransactionController has a default transaction timeout defined as 15 seconds. This can be overridden at runtime by creating a derived instance with a new timeout:
TransactionController controller2 = transactionController.withDefaultTimeOut(50,
TimeUnit.SECONDS); // 1
1 | A TransactionController created using a custom transaction timeout. |
Timeouts can also be modified on a per transaction basis using a Transaction ExecutionBuilder. See the section
Transaction ExecutionBuilder for details.
Note:
The classes in the TCStore transactions framework predominantly follow the immutable builder design pattern. Simply calling the withDefaultTimeout method as shown above is ineffective if the TransactionController instance it returns is not captured/used.