Managing Transactions in Oracle ATG Web Commerce

Most of the Oracle ATG Web Commerce form handlers extend atg.commerce.order.purchase.PurchaseProcessFormHandler. This form handler, which is a subclass of atg.droplet.GenericFormHander, is an abstract class which implements a transaction management pattern that should be followed by any custom form handlers. This transaction management pattern is implemented through the form handler’s beforeSet, afterSet, and handler methods provided as part of the Commerce form handlers.

beforeSet Method

This method is called once before any form handler property is set or handler method is called. It implements the following transactional steps:

  1. If the form handler’s useLocksAroundTransactions property is true (the default), obtain a transaction lock before the transaction is created.

    This prevents a user from modifying an order in multiple concurrent threads. The lock name used defaults to the current profile ID. For more information, see atg.commerce.util.TransactionLockFactory. (Note that use of locking has a small performance impact.)

  2. Check for an existing transaction and, if no transaction exists, create one.

Handler Methods

The handler methods implement the following transactions steps:

  1. Synchronize on the Order object.

  2. Execute logic for modifying the Order object.

    For example, the CartModifierFormHandler subclass has a handleAddItemToOrder method that executes the logic of adding an item to an order.

  3. Call the OrderManager object’s updateOrder method to save the order data to the repository.

  4. End the synchronization.

afterSet Method

This method is called once after all form handler processing is completed. It implements the following transactional steps:

  1. Commit or roll back any transaction that was created in the beforeSet method.

    If the transaction was already in place before the beforeSet method was called, the afterSet method does not end the transaction automatically; this is the application’s responsibility.

  2. If a transaction lock was acquired in the beforeSet method, release the lock.

If you’re extending an Oracle ATG Web Commerce form handler and your code makes its own decisions about errors, you can mark a transaction for rollback by calling the setTransactionToRollbackOnly method.

For more information on PurchaseProcessFormHandler and its subclasses, you can examine the source files at <ATG10dir>\DCS\src\Java\atg\commerce\order\purchase and refer to the ATG Platform API Reference.