Providing an EPL event wrapper for a plug-in

When creating a plug-in, it is considered best practice to provide an EPL event wrapper to access all methods of the plug-in. This provides type safety at runtime with respect to EPL objects of type chunk, that is, opaque objects whose contents cannot be seen or directly manipulated in EPL.

An example of this is the TimeFormat event which is provided as a wrapper for the Time Format plug-in (see also Using the TimeFormat event library). Using the plug-in directly, you can write code such as the following:

monitor UsePlugin {
  import "TimeFormatPlugin" as timeMgr;
  chunk pattern;

  action onload() {
      pattern := timeMgr.compilePattern("EEE MMM dd HH:mm:ss yyyy");
      float stateTimestampSec :=
         timeMgr.parseTimeFromPattern(pattern, "1996.07.10 AD at 15:08:56");
  }
}

Of course there is nothing to prevent someone passing a chunk from another plug-in as the parameter to the parseTimeFromPattern method. You can forestall this possibility and enforce type safety by using an event wrapper instead to hide the chunk type as in the following example:

using com.apama.correlator.timeformat.TimeFormat;
using com.apama.correlator.timeformat.CompiledPattern;

monitor UseEventWrapper {
  CompiledPattern pattern;

  action onload() {
    TimeFormat timeFormat := TimeFormat();
    pattern := timeFormat.compilePattern("EEE MMM dd HH:mm:ss yyyy");
    float stateTimestampSec := pattern.parseTime("1996.07.10 AD at 15:08:56");
  }
}

The event definitions for the TimeFormat and CompiledPattern events can be found in the TimeFormatEvents.mon file, which is located in the monitors directory of your Apama installation. Note how the CompiledPattern event wraps a chunk object, and the parseTime method on the CompiledPattern event uses the chunk in the CompiledPattern object and the string parameter passed in to the action.

This approach gives a more object-oriented feel to using the plug-in and can be used to emulate calling methods on C++ or Java objects. The signatures of actions on event definitions are also available to Apama in Apama Plugin for Eclipse, so they can be viewed there and benefit from completion proposals and type checking.