Skip to content

Event Handler API

Event handling is a feature in Verastream Host Integrator that extends the capabilities of models by allowing you to define specific events that suspend the interpretation of a model and turn control over to user-supplied procedural code.

The Event Handler Guidelines topic provides basic information on designing and implementing event handlers.

Java Event Handlers API

The Java Event Handler API (Javadoc) provides detailed information on the Java classes and interfaces that you can use in your event handler code.

The public API for event handling is largely contained in the com.wrq.vhi.script.api package. Most of the classes and interfaces found in this package fall into one of the following categories.

.NET Event Handlers API

The .NET Event Handler API (available in a Windows help file) provides detailed information on the .NET classes and methods you can use in your event handler code.

Event Handler Classes

There are eight event handler classes, one for each type of object in Host Integrator that can have an event handler attached:

  • LifeCycleEventHandler
  • ModelEventHandler
  • EntityEventHandler
  • AttributeEventHandler
  • OperationEventHandler
  • RecordSetEventHandler
  • FieldEventHandler
  • ProcedureEventHandler

Any class that extends one of these base classes is an event handler and is, by definition, attached to an appropriate object (entity,attribute, etc) in the model. You typically create such a class using the Design Tool, and then modify it using the editor of your choice. Each event handler class defines a set of methods, with each method corresponding to an event in Host Integrator. To implement an event, a derived class simply needs to override one of these methods. For performance reasons, however, it is important to only override those methods that do something beyond the default action.

Event Interfaces

Each method on an event handler class takes a single event interface as an argument. This event interface provides the contextual information for the event and is different for each method. Therefore there is one event interface per event in Host Integrator.

In addition, there is an inheritance hierarchy of intermediate event interfaces that mirrors the object hierarchy in models. Either directly or indirectly, all event interfaces extend the base Event interface. There are intermediate interfaces that are shared by many events such as the EntityEvent interface or the AttributeEvent interface. In fact, the AttributeEvent interface extends the EntityEvent interface because all attributes are defined within the context of an entity.

Callback Interfaces

A few of the interfaces in the com.wrq.vhi.script.api package are for making callbacks to Host Integrator, in order to obtain contextual information, modify the model state, or modify the terminal. When available, these interfaces are obtained via an event’s event interface. The callback interfaces are:

  • ModelContext - Use the methods in this interface to obtain information about the model.
  • ScriptHostSession - Use this interface to get information about the host session and to manipulate the terminal at various levels (direct, model, table).
  • ClientSession - Use this interface to obtain information about the currently connected client.
  • RemoteHostSession (Java Only) - Use this interface to establish a session with a Host Integrator model other than the one containing the event handler.
  • Logger - Use this interface to make entries in the Host Integrator log file.