Guidelines for Developing Event Handlers

The following topics on the structure and behavior of event handlers will help you develop event handlers for objects in a model. You should also consult the event handler examples that are available as part of the Host Integrator Development Kit.

Defining an event handler Nested events
Setting timeouts Session startup/shutdown
Event handler interfaces Error processing
Classpaths Timeout processing
Processing Java code into an event handler Importing event handlers
Best practices Debugging event handlers
Event handler callbacks Troubleshooting event handlers

Defining an Event Handler

Use the New Event Handler dialog box in the Host Integrator Design Tool to generate Java source code that is a template for the new event handler class. Each handler is a Java class that is associated with a specific type of model object (attribute, operation, procedure, etc.) and can be attached to one or more components of that type.

By definition, the event handler class extends a base class specific to the type of model object. This base class is defined as part of Host Integrator.

For each object type, the base class defines a method signature for each supported event. For example, a model event handler has these defined events:

In the user derived class, the declaration of an override for an adapter method signals that the corresponding event is enabled. Otherwise, that event is considered disabled, which means any object that has its events mapped to the user class will not fire the event.

For example, the AttributeEventHandler base class defines two methods for events:

void readAttribute(AttributeEvent e) throws ApptrieveException;
void writeAttribute(AttributeEvent e) throws ApptrieveException;

If a user class overrides the writeAttribute method of the AttributeEventHandler base class, then the write event is considered enabled and the read event is considered to be disabled. You can also extend the event handler definition.

Setting Timeouts

A model's Default event handler timeout setting applies to all events. If a particular event requires a different value, a value can be assigned per event by declaring a static final member of the user's handler class. For example, to set the timeout for the Write Attribute event on a handler to 30 seconds, use this statement:

static final int writeAttributeTimeout = 30;

See information on general timeout processing and timeouts with nested events.

Event Handler Interfaces

The event handler user class has access to all relevant interfaces by calling get<MethodType> methods on the <EventType>Event interface passed into the method. These interfaces include:


A handler is permitted to use any available Java library to assist in meeting the requirements of its script. All libraries placed in the model's scripts\lib directory are included in the classpath for that model, and are introspected for event handler classes. In addition, you can specify a classpath that applies to the local Host Integrator installation with a properties file.

The script manager uses the class loader scheme shown below. The libraries in each model are isolated from each other, and the user class path will take precedence in loading classes. The model's class loader does not use manifest files to find nested JAR files; only class files included directly in the JAR are available.

Processing Java Code into an Event Handler

After the source code is constructed, it is compiled into a Java class (.class file) and the class is placed in a Java Archive (.jar file). It is then available for use as an event handler. Host Integrator provides an Ant script that compiles all Java source files in the model's \scripts\src folder into Java classes in the \scripts\classes folder, and then stores the class files in a single Java Archive in the \scripts\lib folder. Once incorporated in the JAR file, all classes that extend handler adapters for a given object type can be mapped (attached) to any object in that model.

An available event handler can then be assigned to a model object. Most object types have an Advanced Properties option that allows you to attach the handler; the Attach Event Handlers dialog box provides access to all model object types and all available event handlers.

For a given model, all JAR files in the scripts\lib directory will be introspected using the Java reflection API for available event handlers. It is recommended that you use this folder only for event handlers.

Modifying the Event Handler Build Environment

You can modify the ant script (build.xml), located in the models\<modelname>\scripts folder, but remember that the Design Tool uses the following ant targets:

In both cases, the Design Tool defines the following ant properties: