A form handler that can manipulate repository items should ensure that all operations that occur in a handler method call are committed in a single transaction. Committing all operations simultaneously helps ensure data integrity. A repository or database transaction is completed successfully or not at all; partially committed data is rolled back if an error occurs mid-transaction.

The RepositoryFormHandler and TransactionalRepositoryFormHandler classes ensure atomic transactions in this way. If you subclass either class without overriding the handler methods, your subclass handles transactions properly. If you override any handler methods, or add new handler methods, you must make sure that these methods handle transactions properly.

Note: A form handler starts and ends a transaction only when no other active transactions are in progress. If a transaction is in progress, the form handler returns a status for each operation it attempts and permits the transaction to continue after the form handler itself finishes processing.

To create a form handler that works with repository items while a transaction is in progress:

  1. Create a form handler that subclasses RepositoryFormHandler or TransactionalRepositoryFormHandler, depending on your requirements. The source code for both form handlers is provided in

    <ATG10dir>/DAS/src/Java/atg/repository/servlet

    Both form handlers create a transaction if one is not already in progress and provide the status of all operations performed by the form handler while the transaction is in place. The two form handlers mainly differ in the transaction lifespan.

  2. Create methods on your new form handler that are transaction-aware. See Transaction-Aware Methods.

Note: RepositoryFormHandler and TransactionalRepositoryFormHandler are useful for manipulating repository items. The form handler class atg.droplet.TransactionFormHandler supports transactions and lets you work with the JDBC directly.

RepositoryFormHandler

atg.repository.servlet.RepositoryFormHandler is a base form handler that provides tools for creating, modifying, and deleting items stored in an SQL repository. Oracle ATG Web Commerce provides one direct instance of this class, /atg/demo/QuincyFunds/FormHandlers/EmailRepositoryFormHandler.

In the RepositoryFormhandler, the transaction is governed entirely by the submit handler method, meaning the transaction starts when a submit handler method is invoked and ends when it completes execution. Transaction status is reported for the data validation and the data commit operations.

TransactionalRepositoryFormHandler

The atg.repository.servlet.TransactionalRepositoryFormHandler, a subclass of the RepositoryFormhandler, provides enhanced transaction support by broadening the scope of the transaction. This class also defines a few additional properties that are useful for transaction monitoring. Oracle ATG Web Commerce Adaptive Scenario Engine does not include any instances of this class.

Transactions begin when the beforeSet method is invoked and end with the afterSet method. Because a transaction status is generated for all operations that occur during its execution, a status is recorded for each the following operations: