In a state of Transition

Transactions in ACS are currently in a state of transition. The end goal is to have the transaction management be managed by Spring's transaction management framework. Because ACS uses a lot of programmatic transaction management, when we do move to Spring we do not want to have Spring API trickled through out the code base. Instead we will provide a simple wrapper to the Spring APIs. The Transaction class in ACS will be that wrapper. As it stands today, the implementation of that class is still using ACS custom transaction management. As Spring is adopted more and more declarative transaction management will be used and hopefully the usage of the Transaction API class will decrease.

Guidelines on Transaction

In general, avoid transactions in ACS. Transactions should be used solely as a means to do atomic commits across multiple rows. Transactions should not normally be used as a means of error recovery. Because ACS interacts with external resources, operation should not be wrapped in a transaction. If you rollback the transaction, the external resource will likely be in a state inconsistent with what is in the database.

Ideally transactions should be done in DAO methods and not in the service/manager classes.

Transaction API

The transaction class is the new primary API that's should be used for transaction. The usage is as follows

            Transaction.execute(new TransactionCallback<Object>() {
                @Override
                public Object doInTransaction(TransactionStatus status) {
                    // ... do something ...
                    return myresult;
                }
            });

There is also a TransactionCallbackNoReturn if you do not need a return value. When doInTransaction is called a transaction will be started. If doInTransaction executes and throws no runtime exceptions, then the transaction will be committed. If a RuntimeException is thrown the transaction will be rolled back.

TransactionLegacy API

LegacyTransaction is the API that has historically been used in ACS. If you are writing new code in the ACS management server, you should ideally not use this class but instead use Transaction. One reason you may continue to use this class is if you need to create and run a raw SQL statement. In the future there will be a new way for running SQL, but not right now.

For further information on how to use the TransactionLegacy API refer to Data Access Layer

It is generally consider unsafe to use TransactionLegacy in management server code unless you are in a DAO.  Please always use Transaction.

@DB

@DB is in the middle of a transition itself too. @DB can be somewhat confusing as it is mistakenly thought to start a DB transaction. It does not. The @DB adds a check to the method so that on exit transaction will be rolled back if it was not committed.

To further confuse things, the @DB annotation only has any impact when running in the AWSAPI or usage server code. In the core management server, @DB actually does nothing. @DB will be removed as soon as UsageServer and AWSAPI are updated to the new spring modularization style.

DAOs

DAOs have not been migrated to the new transaction API quite yet and still primarily use LegacyTransaction.  If you are writing new code, you should use Transaction, but much of the current code uses TransactionLegacy.

All DAOs that extend GenericDaoBase are wrapped by a spring AOP interceptor that will rollback uncommitted transactions, very similar to how @DB works.

  • No labels