Exception Handling
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 anEngineRuntimeException. - 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
UpdatingBatchcan 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 separateUpdatingBatchbe 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.