Pentagaia toolbox - Tx

The tx library enables direct access to pds transactions. At the bottom of this page there are some important notices about the transaction manager. You should always respect them to develop stable code.

Installation

You can use maven to download and install this module. Add the repository linked in this website's menu to find the modules. You will need one of the following modules depending on the version you are using:

  • tx-0_9_5_1
  • tx-0_9_6

    Maven will manage dependencies. if you are installing manually you will need the following module jar:

  • tx-api

    To run and use this module add the jars to your bootstrap jar. View the installation notes of the start project .

Configuration

You will need no additional configuration.

Use transactions

All information you need is contained in the java doc of interface ITransactionManager . This interface will be installed as a regular pds manager (related service class is named ITransactionService).

Samples

We assume that you are already familiar using the pds transactions. However they will be started and commited in the background. Many services use them (f.e. the pds DataService).

Let us assume that you are running your own java thread. You can use the transaction service to start and commit transactions manually. Look at the following code:

  final ITransactionManager txManager = AppContext.getManager(ITransactionManager.class);
  ITransaction tx = txManager.begin();
  
  // TODO do something, f.e. access the data storage
  
  tx.commit();
  
  // TODO do some other thing that does not need transactions
  
  tx.begin();
  // TODO do the third thing
  tx.commit();

This code fragment starts two independent transactions. After commiting the first transaction there may be some code that does not need transactions at all.

Note:
Many project darkstar features (data storage, tasks and others) use transactions. Using them without starting your own transaction will fail.
Note:
DO NOT ACCESS TRANSACTIONS YOU DID NOT CREATE BY YOURSELF! However it is possible to commit pds transactions. That may be used to implement some kind of commit points during long living services. But be aware that this breaks all managed objects you received before. And pds may be confused because the task manager always tries to commit the transaction you commited before. It will report a task failure and it will log exceptions.
Note:
Your code must always contain a finally statement that tries to commit/abort transactions. Having uncommited transactions in a thread that died may lock the data storage.