Managing Transactions in the ATG Commerce Form Handlers

Most of the ATG Commerce form handlers extend atg.commerce.order.purchase.PurchaseProcessFormHandler, which contains the following methods to facilitate transaction management:

Method	Description
`beforeSet`	Inherited from `atg.droplet.GenericFormHandler`. This method is called once before any form handler property or method is set or called, respectively. The `beforeSet` method is overridden by the `PurchaseProcessFormHandler` class to check for an existing transaction and, if no transaction exists, to create one automatically. If the form handler’s `useLocksAroundTransactions` property is true (which is the default), a transaction lock is obtained 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.)
`afterSet`	Inherited from `atg.droplet.GenericFormHandler`. This method is called once after all form handler processing is completed. The `afterSet` method is overridden by the `PurchaseProcessFormHandler` class to automatically 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. If a transaction lock was acquired in the `beforeSet` method, the `afterSet` method also releases the lock. If you’re extending an ATG Commerce form handler and your code makes its own decisions about errors, you can mark a transaction for rollback by calling the `setTransactionToRollbackOnly` method.

Method

Description

beforeSet

Inherited from atg.droplet.GenericFormHandler. This method is called once before any form handler property or method is set or called, respectively.

The beforeSet method is overridden by the PurchaseProcessFormHandler class to check for an existing transaction and, if no transaction exists, to create one automatically.

If the form handler’s useLocksAroundTransactions property is true (which is the default), a transaction lock is obtained 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.)

afterSet

Inherited from atg.droplet.GenericFormHandler. This method is called once after all form handler processing is completed.

The afterSet method is overridden by the PurchaseProcessFormHandler class to automatically 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.

If a transaction lock was acquired in the beforeSet method, the afterSet method also releases the lock.

If you’re extending an ATG 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 <ATG2007.3dir>\DCS\src\Java\atg\commerce\order\purchase and refer to the ATG API Reference.

ATG Commerce Programming Guide

Managing Transactions in the ATG Commerce Form Handlers