Event Handler Callbacks

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

An event handler performs a mix of custom logic and callbacks to Host Integrator to get information about or modify the state of the model or terminal.

A callback invocation takes place any time an event handler invokes a method on one of the callback interfaces. This may just be asking for information, or it may be a request to modify the model or terminal state.

Note the following properties of callbacks:

• No specific timeout. The governing timeout is that of the event itself. The time allowed per callback extends to the remaining time allotted to the event.
• The event can return the expected data, "normal errors" such as a bad parameter name or a runtime failure in the model, or an event timeout error if the event timeout expires during callback execution.
  

Callback Interfaces

The callback interfaces, as documented in the Javadocs for the Event Handler API, are:

Callback Limitations

• For events that rely on a specific terminal state, callbacks that could change terminal state are disabled within that event. If you attempt this sort of callback, you'll see an error message similar to the following:

  Event handler callback not allowed in current state.  
  An event callback method was invoked at an inappropriate time.  
  

  Click Details in the error message dialog box to see the sequence that preceded this error. The method immediately preceding the error can often tell you the offending callback method. Many events within recordset event handlers (for example, Apply Filter, Parse Screen) and recordset field event handlers (Read Field) disable most callbacks:

• The ScriptHostSession interface cannot be used outside of the event from which it was obtained. In the following events, this interface is not available:
  • Entity Departure (entity event handler)
  • Format Error (model event handler)
  • Most events with life cycle event handlers

• In addition to the limitations within the immediate event handler, callback restrictions apply when event handlers are nested. If an event with callback restrictions is currently open, this limitation will also be enforced for a nested event.