Javascript Engine

The Javascript Engine

Introduction

This script engine is considered in alpha, and should not be used for production

Extending the JSLEE business processing logic can be done using the ScriptEngine component of the JSLEE. By writing JavaScript scripts the JSLEE’s core protocol verticles can be utilised to transform data and perform business logic within the pipeline of the JSLEE.

{
    "selfcare": {
      "handler": "nz.co.nsquared.slee.scriptengine.ScriptEngineVerticle",
      "instance-count": 1,
      "configuration": {
        "scripts": { 
        }
      }
    }
}

Script Configuration

The scripts to run within the JSLEE are configured using the scripts map. An example configuration would be:

{
    "scripts": {
      "nz.co.nsquared.slee.smpp.event.SMPPMessageEvent": "//!sms_selfcare_inbound.js"
    }
}

To configure the JSLEE, the script key must be the fully qualified name of the event that is to be sent over the event bus. This will be a message another JSLEE verticle might send, and must be one of:

Message Class Source
nz.co.nsquared.slee.smpp.event.SMPPMessageEvent This event wraps a SMPP message (e.g. a DeliverSM or SubmitSM)
nz.co.nsquared.slee.edr.EventDataRecord This is an EDR to be written by an EDR interface.
nz.co.nsquared.slee.eventbus.JsonSchemaDocumentEvent This is a generic Json document with a Json schema definition associated with it.

Events of the above forms will be able to come from any endpoint (although there will be natural sources for some), and may be sent on to any other endpoint which understands the message.

To define the script, there are two options:

Conforming to the API

The JavaScript provided must conform to the following API by providing a number of JavaScript methods to perform actual tasks:

Method Required? Description
begin() no This method is called once after a successful evaluation of the JavaScript. This allows for initialisation of the script.
handle() yes This method is called for each incoming event the script engine receives of the type associated with the script.

The handle() Method

The handle method receives the following arguments:

Argument Type Description
eventBus HaEventBus A reference to the JSLEE event bus that can be used to send requests to other JSLEE verticles.
event Event The JSLEE nz.co.nsquared.slee.eventbus.Event object. This will be the subclassed actual event holding the event data.

The handle method must return either:

  1. A two element array [return code, return value], where return code is 0 on success and non-zero on failure. return value is the return value to pass back to calling verticle. On error, this must be a string (or an object whose string value is relevant). On 0, this can be any object.
  2. An integer. 0 on success (in which case the resulting value is null to the calling verticle), or nonzero to indicate an error.
  3. Another form of Java object.

The handle() method shouldn’t return an array other than two elements, nor should it return a non-integer value as the first element in such an array. If it returns a result that is not an integer or an array, it should be a Java class object, not a JavaScript map. (TODO: automatically convert from JavaScript map to Java map).

Throwing Exceptions in JavaScript

If your script throws an exception, please be aware that if the exceptions are thrown in a callback (e.g. a callback handler from calling eventBus.send()), then the exception will be handled by the VertX core message handling system, NOT the execution engine responsible for initiating the JavaScript script in response to a message request.

This is unlikely to be ideal, so it is strongly recommended that callbacks within JavaScript do not throw exceptions.

If an exception is thrown in a JavaScript script outside a per-JS callback, then the exception is handled by the script engine, and will return a failure code to the verticle which send the message through.

Threading

Due to the nature of VertX, each JavaScript script is run in a thread-safe environment and can be written without any fear of multiple threads executing the javascript at once. However note that a script’s execution context will be reused, so this allows a single script to hold global state that is shared across every invocation for a single message. However note that if you run the script engine verticle with more than one instance, then each instance is considered separate.