Event Handler Error Processing

The error processing information below, in combination with other event handler guidelines, will help you develop event handlers that override or extend standard model behavior.

In event handlers, errors are created when a Java exception is thrown. Here are a few examples:

The user code has the ability to trap all exceptions thrown. The following rules apply to the user code for event handler errors:

Rule 1
To communicate standard application errors, an event handler should create and throw an ApptrieveException. This exception can contain multiple messages, each of which is converted into an error message on Host Integrator's internal stack.

Rule 2
Any exception thrown from an event handler that is not an ApptrieveException or a subclass results in a single error message being placed on the Host Integrator stack showing the exception class and the string returned from getMessage().

Rule 3
An event handler may trap and ignore any ApptrieveException it receives from a callback. In this case, however, no error is logged or returned to the client application. If informational logging is turned on, the only evidence of the error condition is an informational log message saying an error was returned to an event handler. Otherwise, Host Integrator does not generate any persistent record of the error.

Rule 4
As an extension of rule 3, an event handler may trap one exception and then throw an entirely new exception with one or more custom messages. This operates as if the event handler initiated the error report (rule 1 or 2 above).

Rule 5
An event handler may trap an ApptrieveException, append its own message, and re-throw the exception. The appended message appears with others generated during the client request.

Rule 6
An event handler is obligated either to not catch or to re-throw an EventTimeoutException. This exception indicates a system state that requires the event handler to terminate and control to be returned to Host Integrator. In any case, any return from the event handler other than the EventTimeoutException is ignored in favor of creating a new EventTimeoutException.

In addition to the standard Host Integrator error stack reporting, any exception caught from user code that is not an ApptrieveException, a subclass of ApptrieveException, or an EventTimeoutException results in the Java stack dump being printed to the Event Handler Console or the designated output file (by default, this is the traps.out file in the <VHI>\etc\output subdirectory).