Using Event Handlers

You can use an event handler to customize the behavior of a model.

The Design Tool offers a variety of features that assist you in creating event handlers. The result is a Java class that conforms to rules for event handling. This class is then mapped (attached) to specific objects of a model to customize its behavior.

You can attach event handlers to events associated with the entire model, a life cycle event, or to entities, attributes, operations, recordsets and recordset fields, and procedures. You can reuse a handler in multiple models or with multiple objects of the same type within the same model.

To create an event handler:

1. Navigate to the object in the model that relates to the behavior in the model that you want to extend or override.
2. Use the New Event Handler dialog box to generate a basic template that includes the supported events for that handler type.
3. Edit the template in your default editor to add the event functionality. Methods for all supported events are included in the template, but they are commented out (disabled). Enable the event by defining the corresponding method.
4. Rebuild the model JAR or .NET application extension file. Once the class is in the model JAR or .NET application extension file, it can be mapped to a model object. You can repeat the rebuild at any time, even if the event handler is already attached to an object.
5. Attach the handler to the selected object in the model. You can attach the same handler to multiple objects. No rebuild is required.

The procedure for testing the event handler will vary according to the type of event you are creating.

Build Event Handlers For Check-in To Source Control

A commandline utility is now available to build event handlers in a Windows Development Kit installation. Close the Design Tool before running the following batch files.

In the VHI\bin directory, there are two files:

• buildeventhandlers.bat - builds event handlers for a specified model
• cleaneventhandlers.bat - cleans executables from the event handler, leaving behind source code. Used to prepare the model for check in to source control.

The batch files each take a single argument. The argument is a path to the directory containing the model with event handlers.

Working With Existing Models

To use the cleaneventhandlers.bat file with existing models from VHI 6.6 or earlier, you can either copy the new build.xml from <VHI install folder>\lib\scripts\java\templates,or edit the custom build.xml by adding the following commands to the clean model target:

• <delete file="${vhi_model.jar}" >
• <delete file="tmp/vhi_model.jar" >

Example

Review a sample event handler that reformats currency amounts in recordset fields.

About Event Handlers

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

One use of event handlers is to improve the presentation of host data in new client applications. For example, you can use event handlers to:

• Convert cryptic host application codes to user-friendly descriptions
• Convert formats for currencies or dates
• Secure access to sensitive data
• Create other functions that might otherwise require custom client-side programming

You can also use event handlers to extend the Host Integrator error-handling capabilities. For example, you can add an event handler at the point the error occurs and then implement event-handler code that intercepts the error, takes control, and corrects the error.

Implementing Event Handlers

You can attach an event handler to any of the following model objects. For each of these eight varieties of event handler, there are one or more defined events. Click each model object type to see details on the events and possible uses for event handlers associated with each.

• The model
• The "life cycle" (events such as Model Load, Model Unload, Authenticate User) that occur as the server manages sessions with the model.
• An entity
• An attribute
• An operation
• A recordset
• A recordset field
• A procedure

Creating, Building, and Deploying Event Handlers

Use the Design Tool to review and select event handler attachment points, configure your event handler development options, and build event handler templates. (The templates are code stubs that provide a starting point for your own event handler.) You can build, load, attach, and test event handlers within the Design Tool.

The current version of Host Integrator supports development of event handlers in Java. After you create an event handler template in the Design Tool, you can implement the handler with any appropriate third-party editor. Event handlers are packaged and deployed with a Host Integrator model.

Once event handlers are deployed, they are managed by the script manager, which runs with both the Design Tool and the Session Server. An event source is a specified point in the execution of a model, such as the reading of an attribute, the authentication of a user, or the writing of a recordset field. An event source generates an event only if the corresponding event method is implemented in the attached event handler. The event delivered to the event handler describes the environment in which the event occurred. The event handler code uses this description to accomplish its task.

In a Development Kit installation, you can build Java or .NET event handlers outside Design Tool.

The following batch files are located in the C:\Program Files\RocketSoftware\Verastream\HostIntegrator\bin folder:

• buildeventhandlers.bat: Builds event handlers for a specified model. For example, <model folder>\scripts\lib\vhi_model.jar is created for Java event handlers.

• cleaneventhandlers.bat: Cleans executables from the specified model event handler subfolder, thus retaining source code only. Used to prepare the model for checking into a third-party source control system.

Note the following

• Close the Design Tool application before running these batch files.

• Each batch file requires a single command line argument, the complete model directory path.

• For Java, the cleaneventhandlers.bat file requires the build.xml file to be present in the <model folder>\scripts folder, which is automatically generated for models created by Design Tool version 6.6.188 and higher. For existing older models, you can either copy build.xml from <VHI>\lib\scripts\java\templates, or edit your custom build.xml by adding the following commands to the clean model target:

  <delete file="${vhi_model.jar}"/>

  <delete file="tmp/vhi_model.jar"/>

• For .NET, the cleaneventhandlers.bat file requires the build.proj file to be present in the <model folder>\scripts folder, which is automatically generated for models created by Design Tool version 7.0. and higher.

• After running buildeventhanders.bat and re-deploying an existing model on the session server, the updated event handlers do not take effect for existing idle pooled sessions (since the model version is not updated) and new client connections until you do one of the following:

• Undeploy the model using the deactivatemodel command before re-deploying -or-

• After re-deploying, stop and start the associated session pools in Administrative Console, or restart the session server

  -or-

• After re-deploying, in the Administrative Console Sessions view, select idle sessions, and Terminate the Session from the Host. Idle pooled sessions are automatically re-connected as specified by each pool's configured minimum idle sessions.

• Instead of using buildeventhandlers.bat, rebuild the event handler within the Design Tool before you re-deploy the model. This updates the model version. Idle pooled sessions are automatically re-connected.

Features

Host Integrator has tools and visual indicators to assist you as you create and incorporate event handlers into your model:

• Design Tool visual indicators

  • Within the Design Tool, objects with attached event handlers are identified with a lightning bolt displayed to the left.

  • The status bar includes symbols that indicate if a script manager reset is needed or if event handlers should be updated.

  • The event handler toolbar offers shortcuts for standard Design Tool tasks associated with event handlers

• Event Handler configuration

  Use event handler settings to configure your editing, building, debugging, and environment preferences.

  You can modify other configuration options in properties files. You can also set up security for event handlers using configuration files.

• Developing event handlers

  Use the options on the Events menu to build, edit, and attach event handlers to objects. From this menu, you can also open the libraries and sources folders for event handlers, reload and rebuild handlers, and disable event timeouts.

• API support

  There is complete API support for event handlers, for both Java and .NET. See the Event Handling API topic.

• Examples

  An event handler example is provided with Host Integrator.

• Debugging tools for event handlers

  Additional tools are available for debugging event handlers.

Best Practices

For best results within the event handler runtime environment, follow these guidelines for optimizing your event handlers:

Design considerations

Do not implement unnecessary event handlers

Do not store state information in handler classes

Synchronize the model hash table

Use of multithreaded objects is discouraged

Limit use of output streams

Use a class path folder for JAR files that do not contain event handlers

Design Considerations

The runtime environment for Host Integrator event handlers is similar to that of JSP servlets.

Handlers are treated as stateless objects running in the context of a single thread. State information is stored in two system-administrated hash tables:

• One for each model, available to all client and host sessions using that model

• One per client session, where each client connection creates a new client session

The ModelContext and ClientSession interfaces provide methods to add, remove, and access objects stored in the respective hash tables.

Do not implement unnecessary event handlers

Event handlers are intended to override or augment default behavior. Don't implement an event handler that makes no change to the default behavior, as it will affect server performance.

Do not store state information in handler classes

Handler classes should not generally use member objects to store state information. This state information often spans client sessions, which creates the risk of crosstalk and makes state information vulnerable to unexpected behavior by the model in the context of an error. If a situation arises where state members are needed, access to the member object must be thread-safe (accessible by multiple threads at once, as in read-only objects, or making use of locks to prevent simultaneous access).

Synchronize the model hash table

Objects stored in the model hash table must also be thread-safe, as multiple client sessions could gain simultaneous access to them. The only events that are guaranteed to have sole access to the model hash table are Model Loaded and Model Unloaded. Objects stored in the client hash table are guaranteed to only be accessed by a single thread at a time; a client session may have several events in progress, but only one can actually be executing code at a time.

Use of multithreaded objects is discouraged

Just as in many JSP Servlet environments, Host Integrator does not actively prevent use of objects that start additional threads. However, as the event handlers are event driven via the controlling Host Integrator application, there is no explicit support for such objects because there is little direct advantage to be gained. In many cases, Host Integrator's behavior is dependent on host responses or client inputs; under these constraints, multithreaded event handlers can be easily placed in positions that rely on undefined behavior to function correctly. If you must use undefined threads, use sound Java programming concepts.

Limit use of output streams

Limit use of System.out and System.err streams. Blind calls to the output streams are wasteful and not a best practice. Using these outputs has a performance impact (often up to 15%). One recommendation is to code each call to check for applicability before the arguments are constructed, assembled, and the call made. The criterion for whether a call is applicable may vary, but the following example addresses the problem:

if (event.isDesignEnvironment()) {
   System.out.println("Here I am. The count is " + count);
   }

if (vsEevent.IsDesignEnvironment())
 {
    Console.WriteLine("Here I am. The count is " + count);
 }

This simple check prevents the allocation of a StringBuffer, a String append, conversion of an int to a String, another String append, entering/exiting of the stream's synchronization monitor, and a few other steps.

Use a class path folder for JAR files that do not contain event handlers

JAR files that do not contain event handler classes should be placed on the user class path, not in the model's \scripts\lib directory, to avoid the overhead of introspection. Introspecting more than 1 MB of JAR files in the model's event handler directory may cause delays in the Design Tool and slow down Server startup.

More information

• Event Handler Guidelines
• Troubleshooting Event Handlers