Nashorn-based Script Filter
This component is deprecated as of Kura version 5.3 since no more available on Java 17.
The Script Filter Component provides scripting functionalities in Kura Wires using the Nashorn Javascript engine:
- The script execution is triggered when a wire envelope is received by the filter component.
- It is possible to access to the received envelope and inspect the wire records contained in it form the script.
- The script can optionally emit a wire envelope containing one or more wire records for each wire envelope received.
- The script context is persisted across multiple executions, allowing to perform stateful computations like running a counter, performing time averages etc.
- A slf4j Logger is available to the script for debug purposes.
- The script context is restricted in order to allow only Wires related processing. Any attempt to load additional Java classes will fail.
- The default configuration contains an example script describing the component usage, it can be executed connecting a Timer and a Logger component.
Usage
The following global variables are available to the script:
input
: an object that represents the received wire envelope.output
: an object that allows to emit wire records.logger
: a slf4j logger.
The following utility functions are available:
newWireRecord(void) -> WireRecordWrapper
newByteArray(void) -> byte[]
newBooleanValue(boolean) -> TypedValue
newByteArrayValue(byte[]) -> TypedValue
newDoubleValue(number) -> TypedValue
newFloatValue(number) -> TypedValue
newIntegerValue(number) -> TypedValue
newLongValue(number) -> TypedValue
newStringValue(object) -> TypedValue
The following global constants expose the org.eclipse.kura.type.DataType
enum variants:
BOOLEAN
BYTE_ARRAY
DOUBLE
FLOAT
INTEGER
LONG
STRING
Received envelope
The received envelope is represented by the input global variable and it has the following properties:
- emitterPid: the emitter pid of the received envelope as a String.
- records: an immutable array that represents the Wire Records contained in the Wire Envelope.
Each element of the records array is an immutable object that represents a received wire record. Wire record properties are directly mapped to Javascript object properties, and are instances of the org.eclipse.kura.type.TypedValue
class. Each Wire Record property has the following methods available:
getType(void) -> DataType
: Returns the type of the value, as a DataType enum variant. Can be matched against the data type constants described above.getValue(void) -> Object
: Returns the actual value.
The javascript objects referred as WireRecords in this guide are not instances of the org.eclipse.kura.wire.WireRecord
class, but are wrappers that map WireRecord properties into javascript properties. The following code is a simple example script that show how to use the filter:
// get the first record from the envelope
var record = input.records[0]
// let's assume it contains the LED boolean property and the TEMPERATURE double property
record.LED1.getType() === BOOLEAN // evaluates to true
if (record.LED1.getValue()) {
// LED1 is on
}
record.LED1.getType() === DOUBLE // evaluates to true
if (record.TEMPERATURE.getValue() > 50) {
// temperature is high, do something
}
Creating and emitting wire records
New mutable WireRecord
instances can be created using the newWireRecord(void) -> WireRecordWrapper
function. The properties of a mutable WireRecord
can be modified by setting Javascript object properties. The properties of a WireRecord
object must be instances of the TypedValue
class created using the new<type>Value()
family of functions. Setting different kind of objects as properties of a WireRecord
will result in an exception.
The output global variable is an object that can be used for emitting WireRecords.
This object contains a list of WireRecords that will be emitted when the script execution finishes, if no exceptions are thrown. New records can be added to the list using the add(WireRecordWrapper)
function. It is also possible to emit records contained in the received WireEnvelope.
The script filter will emit a wire envelope only if the WireRecord list is not empty when the script execution completes. The following code is an example about how to emit a value:
var byteArray = newByteArray()
byteArray[0] = 1
byteArray[1] = 2
byteArray[2] = 0xaa
byteArray[3] = 0xbb
record.LED1 = newBooleanValue(true)
record.foo = newStringValue('bar')
record['myprop'] = newDoubleValue(123.456)
record['example.long'] = newLongValue(100)
record['example.float'] = newFloatValue(1.014)
record['example.byte.array'] = newByteArrayValue(byteArray)
output.add(record)
Script context
The script.context.drop option allows to reset the script context. If set to true
the script context will be dropped every time the component configuration is updated, resetting the value of any persisted variable.
In the example below, with script.context.drop=false the following script will preserve the value of counter
across executions. Setting script.context.drop=true will cause counter
to be undefined
every time the component is triggered.
counter = typeof(counter) === 'undefined'
? 0 // counter is undefined, initialise it to zero
: counter; // counter is already defined, keep the previous value
Updated 10 months ago