Guidelines for Developing Event Handlers

Use these topics on the structure and behavior of event handlers to develop event handlers for objects in a model. You should also consult the event handler examples (located in Micro Focus\Verastream\HostIntegrator\examples\EventHandlers\java\documentation\index.html) that are available as part of the Host Integrator Development Kit.

Defining an event handler Best practices
Setting timeouts Nested events
Event handler interfaces Session startup/shutdown
Java Classpaths Error processing
Processing Java code into an event handler Timeout processing
.NET Assemblies Importing event handlers
Processing .NET code into an event handler Debugging event handlers
ScriptHostSession API Troubleshooting event handlers
Security configuration  

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 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:

Java

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

.NET

public override string ReadAttribute(IReadAttributeEvent vsEvent)
public override void WriteAttribute(IWriteAttributeEvent vsEvent)

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. See information on general timeout processing and timeouts with nested events for more information.

Java

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;

.NET

If a particular event requires a different value, a value can be assigned per event by using the Timeout attribute. For example, to set the timeout for the Write Attribute event on a handler to 30 seconds, use this statement:

[Timeout(30)]
public override void WriteAttribute(IWriteAttributeEvent vsEvent)

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:

Java Classpaths

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 Java 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:

.NET Assemblies

A handler is permitted to use any available .NET Application Extension (DLL) to assist in meeting the requirements of its script. All .NET Application Extensions placed in the model's scripts\lib directory are included in the assembly for that model, and are introspected for event handler classes.

Processing .NET Code into an Event Handler

After the source code is constructed, it is compiled into a .NET Application Extension (DLL). It is then available for use as an event handler. Host Integrator provides a project file that msbuild uses to compile all .NET source files in the model's \scripts\src folder and subfolders into a .NET Application Extension in the \scripts\lib folder. Once msbuild has completed, 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.

Modifying the .NET Event Handler Build Environment

You can modify the project build.proj, located in the models\<modelname>\scripts folder. The Design Tool will invoke msbuild so that the default target is built.

Related Topics
Bullet About event handlers
Bullet Attach event handlers