The following exception handling
guidelines apply to action handlers.
Unlike other action
handlers, a custom sweep handler does not run in a Java™ Platform, Enterprise Edition (Java EE) transaction.
- Except for custom sweep handlers, action handlers run in a Java EE transaction. The server
makes extensive use of Java EE
transactions to ensure that persisted data is correct and consistent.
To avoid undermining the transactional consistency of the server,
handler code must always throw some exception in response to an exception thrown
by the Content Engine API. Throwing
the exception ensures that the server rolls back the surrounding transaction
and cleans up any inconsistent database activities. It is not safe
to catch a Content Engine API
exception and treat it as a soft or recoverable failure.
- You must wrap any thrown checked exception with a subclass of RuntimeException.
The server catches a thrown exception and wraps it with an EngineRuntimeException.
- Custom sweep handlers must ensure that in the event of a failure,
they don’t leave partial effects in place. In addition, custom
sweep handlers must be idempotent (tolerant of operations applied
multiple times even if successful the first time).
Although custom
sweep handlers do not run in Java EE
transactions, operations they perform by using the Content Engine API have the normal transactional
behavior, and, in particular, an UpdatingBatch can
be used to run a set of actions atomically. This is the ideal way
to ensure that operations do not leave partial effects in the event
of an error. If this approach is used, it is recommended that a separate UpdatingBatch be
applied for each sweep item in the batch that is passed to the handler
so that each item is either processed successfully or fails completely
independently from all others.
Avoid allowing
exceptions to propagate beyond the handler. Trap exceptions and set
the outcome method on sweep items.