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.

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:

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:

  ant [build]   Recompile all source files and generate the Javadocs.
  ant clean   Remove all compiled output files and Javadocs
  ant noop   Test the ant build files.

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 5005) 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.