The BSFMonitor poller monitor class currently can use only the expression-evaluation mode of running a script, which limits its usefulness for many BSF-supported languages. Jython in particular has a unique idea of what constitutes an expression (a single line of code containing only simple expressions, no method or function calls allowed). There also is currently no provision for returning response-time data from a script to the poller via this monitor. Third, only "available" and "unavailable" service status can currently be indicated with this monitor; there's no provision for the "unknown" and "unresponsive" statuses. Finally, there is currently no provision for allowing the scripts to use OpenNMS' logging infrastructure.
This enhancement addresses all of these shortcomings while attempting to preserve backward compatibility. A new service parameter called "run-type" is now recognized. If it's not present or is set to "eval", then the old behavior more or less stands: the script should evaluate to an object whose string value is "OK" if the service is up. The new status tokens of "UNK" (unknown), "UNR" (unresponsive), and "NOK" (unavailable / Not OK) are also recognized in this mode. Any value other than those four is assumed to mean, as before, that the service is down and that the value itself should be used as the reason code for the resulting nodeLostService event that the poller creates. In eval mode when the status is "OK", a single response time in milliseconds will be passed back to the poller as measured from just before the eval began until just after it ended.
If the new "run-type" parameter is present and set to a value of "exec", then the script will be executed using the BSFManager's "exec" method. Since executed scripts cannot return values, we now declare two new beans in addition to the existing ones:
results: a HashMap into which the script can do put(String, String) to pass values back to the BSFMonitor and on to the poller. An entry in this map with a key of "status" and containing one of "UNK", "UNR", "OK", or "NOK" will be recognized as representing a service status of unknown, unresponsive, available, or unavailable, respectively. Other values in this entry are illegal and will cause the service to be marked as down and a warning message logged. An entry in this map with a key of "reason" will have its value passed back to the poller as the reason code for the resulting nodeLostService event if the status is other than "OK".
times: a LinkedHashMap into which the script can do put(String, Number) to pass one or more response-time values. A script may set an entry in this map with a key of "response-time" to represent the duration of the whole transaction; if this entry is not provided, the BSFMonitor will substitute a time in milliseconds as measured from just before the execution was started until just after it returned. A script may set zero or more other entries into this map to create a multi-valued response such as those returned from the StrafePingMonitor and MemcachedMonitor classes. Note that this bean is available to scripts running in eval mode, but many BSF-supported languages will not be able to use it.
bsf_monitor: the singleton instance of the BSFMonitor class itself. A new method log(String sev, String fmt, Object... args) serves as a pass-through to the static LogUtils.warnf(Object, String, String, Object...) et al methods.
Note that this enhancement makes no attempt to make the BSFMonitor more efficient or more scalable – it still does not try to cache the compiled bytecode of the scripts that it runs. Still, it's probably considerably less burdensome to use than the GpMonitor (which uses System.runtime.exec() to do its very dirty work) for one-off monitors to be used on a small scale.