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:
- A JavaScript script can be provided inline to in the
scripts
tag. For very short scripts this might be reasonable, however in practice this is suggested only for debugging and testing (e.g. to dump the received message before passing on to the real endpoint). - A JavaScript script stored in a file can be referenced by the first characters of the inline
script being
//!
- the equivalent of the Shebang for command line scripts. The content of the inline script will be evaluated, then the content of the file referenced will be evaluated. This allows some ability to override a file’s content for a specific configuration & deployment.
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:
- A two element array
[return code, return value]
, wherereturn 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. - An integer. 0 on success (in which case the resulting value is null to the calling verticle), or nonzero to indicate an error.
- 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.