Scripting

Overview

mqtt-spy & mqtt-spy-daemon provide a mechanism to script message publications and processing of received messages. This is done by running a script written in JavaScript (that is compliant with the Java Nashorn specification).

Publishing messages

All following sections apply to both mqtt-spy and mqtt-spy-daemon, unless stated otherwise.

Interface between mqtt-spy/mqtt-spy-daemon and scripts

Most interaction between a script and mqtt-spy/mqtt-spy-daemon is done via the mqttspy object.

Publishing messages

In order to publish messages, the script must call an appropriate method on the mqtt object. There are two methods available for publishing messages:

• mqtt.publish(topic, stringPayload);
• mqtt.publish(topic, stringPayload, qos, retained);
• mqtt.publish(topic, binaryPayload, qos, retained);

For an example of publishing a binary payload see https://github.com/kamilfb/mqtt-spy/blob/development/mqtt-spy/src/test/resources/scripts/publish_image.js

Publishing parametrised messages (mqtt-spy only)

mqtt-spy, apart from supporting standard manual publications, allows you to define your message parameters (i.e. topic, payload, QoS, retained) and then pass it to a chosen script for publication.

This allows you to enrich the message, e.g. by adding a timestamp, sequence number, digital signature, or defining your custom message envelope or encoding.

The defined message is available as a message object in your script, so for instance you can do:

mqtt.publish(message.getTopic(), message.getPayload(), 0, false);

For more details see the 'Interacting with message objects' section.

Supporting methods

The spy object exposes additional helper methods:

• var result = mqttspy.execute(command); - executes a command line command (e.g. call a system command)
• var success = mqttspy.instantiate(className); - instantiates a class with the given package name and class name, e.g. by passing com.test.MyClass, the following object com_test_MyClass becomes available, e.g. var myResult = com_test_MyClass.myCustomMethod();

Message audit log replay

For details see the Message Audit Replay wiki.

Script health reporting

mqtt-spy keeps an eye on the running scripts, detecting whether the script is publishing messages or reporting it is not frozen. If the script is to perform regular long sleeps, use the spy.setScriptTimetout(timeoutInMilliseconds); method to increase the default value of 5 seconds (5000ms).

If the script is to perform other actions than message publications, and they might take a long time, call spy.touch(); to inform mqtt-spy that the script is alive and running OK.

Interacting with the script from the UI (mqtt-spy only)

Each script can be started from the UI. Once running, a request to stop the script can be issued. That request is only going to be handled if the script calls methods the react to the interrupted status of a thread they are running in. One of those methods is Thread.sleep(timeToSleep);.

For samples see the Scripted publications wiki.

Processing received messages

There are three main uses for processing received messages with a script:

• Auto-reply, based on the content of the received message
• Reformatting the message before displaying it or logging it (e.g. removing custom message envelope or encoding)
• Triggering other actions (e.g. diagnostic logging, executing system commands)

The script to run is configured per subscription, and passed to the message as receivedMessage object.

For how to configure a subscription script and samples see the Scripted subscriptions wiki.

Search messages

For details see the Message Search wiki.

Interacting with message objects

Whether accessing message parameters before publication (message object), or processing a received message (receivedMessage object), the following methods are available:

• String getTopic(); - retrieves the message topic
• String getPayload(); - retrieves the message payload as string
• void setPayload(final String payload); - sets the message payload (so that for instance you can reformat the message before displaying it or logging)
• int getQoS(); - gets the quality of service
• boolean isRetained(); - gets the retained flag
• byte[] getRawPayload(); - gets the binary payload of the message
• void setRawPayload(final byte[] payload); - sets the binary payload

Diagnostic logging

mqtt-spy & mqtt-spy-daemon also expose their logger (log4j) to their scripts. The object is simply called logger, and exposes all standard slf4j/log4j methods, e,g. logger.info("Reading XML from a file...");

Help

If you need further help, search for "java nashorn" and you should get plenty of examples. If still struggling, tweet to @mqtt_spy.