Event Handler Nested Events

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

Host Integrator's event handler architecture permits an event handler callback to invoke another event handler.


A procedure event handler can issue a request to execute an operation. If the model happens to map the operation to an event handler, then a nested event handler invocation takes place. In this runtime situation, the operation event is considered to be the child or descendant of the procedure event, while the procedure event is defined as the parent or ancestor of the operation event. This is a transitory relationship that exists only as long as both event handlers are in progress.

Further, the operation event handler can request to read data from an attribute, where the attribute has a handler with the Read Attribute event defined. This process of nesting can continue to whatever level is dictated by the callback and event handler constructs of the user model.


Host Integrator imposes one limitation on nested events: the same event on the same object cannot be signaled more than once in the same nesting structure. A nested request to invoke the same event on a given object results in an error being reported to the event handler that issued the callback request.


Errors returned from a nested event are propagated to the parent event handler in the form of an ApptrieveException result on the parent event handler callback. Host Integrator may add one or more additional messages to the stack when formulating its callback response.

When a nested event returns an exception, that error is propagated to the immediate ancestor event. If the exception is not an EventTimeoutException, the ancestor event is permitted to catch the resulting Java exception and proceed with the logic in the "catch" portion of the try-catch block surrounding the callback request. If the event handler completes its task within the time allotted and does not return an exception, then the event is considered a success and normal processing continues.


For background, see general timeout processing information for event handlers.

With nested events, the event with the smallest amount of remaining time governs the interval before a timeout notification takes place.

In the case discussed here, a procedure includes an operation that includes a request to read from an attribute. If a procedure with a 30-second timeout has been running for 15, an operation with a 10-second timeout has been running for 7, and the attribute has a 5-second timeout, the attribute event times out in 3 seconds (when the operation timer expires).

When a timeout occurs in a nested situation, some special processing rules apply.

At any given time, only one hierarchy of events can be in progress. The first event in the hierarchy is the primary event. All the errors reported from primary event handlers result in failure of the client request, but this is not the case for nested events.

If the operation times out in the example used here, both the nested attribute and operation event handlers receive and return EventTimeoutException results. For the procedure event handler containing the primary event, the operation timeout represents a simple failure. The procedure event handler receives an ApptrieveException result reporting the timeout. The procedure event can attempt recovery or otherwise continue processing to completion.