Event Handler Best Practices

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

Design considerations

Don't implement unnecessary event handlers

Don't store state information in handler classes

Synchronize the model hash table

Use of multithreaded objects is discouraged

Limit use of System.out and System.err streams

Use a class path folder for non-event-handler JAR files

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:

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

Tip: For Java, you can use java resources in Host Integrator event handlers. For .NET, you can use third party or your own custom assemblies in Host Integrator .NET event handlers by placing them in the model's scripts\lib folder

Don't 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.

Don't 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 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:

Java:

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

.NET

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.

Java: Use a class path folder for non-event-handler JAR files

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.

Related Topics
Bullet Adding event handlers
Bullet Event handler guidelines