Synchronous and asynchronous methods

Each method in the Groovy DI API is defined as synchronous or asynchronous, and is respectively executed as such. The simpler operations which instantly return a value and do not require any execution on the device, for example get device ID or get feature ID, list devices, etc. are usually synchronous methods. Those which require communication with the device and sending commands to it, for example the exec() method, are usually asynchronous.

It is of vital importance for Bosch IoT Manager to support asynchronous methods because of the devices' nature of sending and completing requests. Normally, management actions upon devices are done by sending remote commands/messages to the physical targets, therefore being long-time consuming tasks. Considering also the significant number of managed devices the system aims to operate, there needs to be a non-blocking way to execute such a big number of time-consuming actions in parallel.

Asynchronous methods allow commands that are sent to devices to be confirmed after the Groovy method body returns, which potentially may happen long after the Groovy script execution is finished.

Synchronous method example

Getting the ID of a device object:

Device myDevice = di.device("myDeviceId")
String myDeviceId = myDevice.deviceId()

The method deviceId() is synchronous and immediately returns the ID of the device object without having to process anything in the background. After this method has returned a value, the next method can be called.


Asynchronous method example

Installing a bundle:

Device myDevice = di.device("myDeviceId")
myDevice.exec(
"BundleFactory",
"install",
['http://myrepository/com.bosch.iot.dm.lamp-5.0.3.jar', ['-s'].toArray()].toArray())

The target.exec() method is asynchronous and just sends a command with the install location to the device and exits, without waiting for it to download the bundle content and perform the real installation. The bundle installation is completed on the background, i.e. asynchronously. This allows mass simultaneous execution of a large number of commands to the managed targets.

As some dynamic methods may not be listed in the Groovy APIs documentation, consider that they are always asynchronous methods.

When using our Groovy API documentation be informed that the AsyncResult last argument, found in some methods in our groovy doc should be ignored and not included in the actual action script as it merely indicates that this concrete method is asynchronous.