Purpose

The purpose of the event handler examples is to illustrate using event handlers in a variety of common tasks. The examples also illustrate several best practices related to how to share code among event handlers, how to create objects that can be safely shared among event handlers, and how to simplify the maintenance of event handler code.

Organization

The examples are organized as a set of standalone Host Integrator models, event handlers, and an ant build file. The links on the left side of this page display documentation for each type of event.

Some of the examples share the implementation of utility classes, which are described by the shared classes topic.

The examples as installed contain Javadocs generated from the event handler source code. The Javadocs are stored in a scripts/doc subdirectory with each model. The links on the left side of each event example page display the Javadocs for the example event handlers.

Building the Examples

Using the Verastream Design Tool

Each example includes an ant build file (build.xml). The build files are modified from the one that is automatically generated by the Design Tool, but they are still fully compatible with the Design Tool's Rebuild Event Handlers command.

• Each example build file contains a docs target which generates the Javadocs for the event handler source code. The docs target is not used when building from the Design Tool, since the Javadoc tool is not installed by Verastream.
• The examples which depend upon shared libraries (AttributeEvents and LifeCycleEvents) contain a dependency on some shared libraries. This dependency will recompile and copy the shared libraries to these projects when necessary.
• The Format Events AbbreviationsDB example copies an external JDBC driver Jar file into the example's scripts/lib directory. You must install your own database and JDBC driver to run this example, and the build file must be modified to copy the JDBC driver Jar file from its installation directory to scripts/lib.

Compiling Individual Example Event Handlers

In order to generate the Javadocs you must install the Java SDK (version 1.4.0) available from Sun Microsystems. You must also run the ant program from a command shell, while setting the PATH, JAVA_HOME, and ANT_HOME environment variables as follows:

• Add the VHI/jre/bin directory at the front of the PATH.
• If you have installed the Java SDK from Sun, add the SDK's bin directory after the VHI/jre/bin directory on the PATH.
• Set the JAVA_HOME variable to the Java SDK directory.
• Set the ANT_HOME variable to the VHI/ant directory.

To regenerate the documentation run ant directly from a command line, or from the Windows Start:Run menu, and enter the command:

		ant "-Dvhi.jars.dir=C:/Program Files/vhi/lib/java" docs
	

Replace the directory path C:/Program Files/vhi with a path to the directory in which the Host Integrator is installed. The -D argument tells the build script where to find the Jar files which define the Verastream event handler environment.

To remove the documentation use the command:

		ant cleandocs
	

Compiling all Event Handlers

The top-level EventHandlers/java directory contains an ant build.xml file. Running ant in this directory will rebuild all of the event handler examples.

The ant program must be run from a command shell, while setting the PATH, JAVA_HOME, and ANT_HOME environment variables as detailed above.

The ant targets available are:

To rebuild all of the examples, run ant directly from a command line, or from the Windows Start:Run menu, and enter the command:

		ant "-Dvhi.jars.dir=C:/Program Files/vhi/lib/java"
	

or

		ant "-Dvhi.jars.dir=C:/Program Files/vhi/lib/java" build
	

Replace the directory path C:/Program Files/vhi with a path to the directory in which the Host Integrator is installed. The -D argument tells the build script where to find the Jar files which define the Verastream event handler environment.

To remove all generated files (compiled classes, Jar files, and documentation) use the command:

		ant  "-Dvhi.jars.dir=C:/Program Files/vhi/lib/java" clean
	

setting the parameter vhi.jars.dir as appropriate.

Running the Examples

Using the Design Tool

Most of the examples can be exercised by opening the example model in the Design Tool. This is especially convenient if you want to make changes to the example code and to see the effects of those changes in the model's operation.

Each of the individual examples will describe how to use the Design Tool to invoke the event handlers. Doing this usually employs one or more of the Design Tool's model debugging tools (for recordsets, procedures, lifecycle events, and so forth).

If you are using a Java IDE which provides for source debugging, the Script Manager started by the Design Tool will have a debug port (default is port 5006) open so that you can use a debugger to set breakpoints or monitor variable values. Be sure to turn off the Event Handler timeouts when using breakpoints.

Use the Event Handler Console to display output from the Java System.out and System.err streams.

Using the Web Builder

The Verastream Web Builder can generate web applications to display data retrieved from the example models. This provides a convenient way to use a real application to test the examples when they are deployed to a Verastream Server.

If you want to debug models deployed to a Verastream Server, you should enable event handler debugging on that server. You can do this by enabling the Server's Java debugging port and by configuring output files for the System output streams and for exception trap traces.

• Use the Server Properties page in the Administrative WebStation to enable Script Manager debugging and to disable event handler timeouts. The Server Properties page will also display the number of the port opened by the Script Manager for remote debugging.
• Edit the VHI/etc/script.properties file to enable System.out and System.error output. Writing exception trap traces to a file is also helpful when debugging event handlers.