Async

By using the broker.async* services, it is possible to access to functions related to asynchronous messaging among different mat|r devices.  

Mat|r device: This refers to either a mat|r app running in a specific broker or an IoT device configured from the mat|r platform.

 

PUBLIC METHODS

void broker.async.initialize()

It performs all the corresponding mat|r device configurations to allow the communication among channels. This call is required before the call to the connect method.  The service is initialized only once when executing the app, this means that the following calls will be ignored.

NOTE: in case the device has already been initialized with metadata, this will remain unmodified.

 

Exceptions
AsyncServiceError – Has been an exception in async service ‘initialize’. There is an error when initializing a mat|r device (connection error | server error)

 

void broker.async.initialize(Map metadata)

It initializes the mat|r device and links additional information: metadata, which could be null or empty.

 

Arguments
metadata Map<String>: additional information to associate to mat|r devices.

 

Exceptions
AsyncServiceError – Has been an exception in async service ‘initialize’. There is an error when initializing a mat|r device (connection error | service error).

 

void broker.async.connect()

It connects the mat|r device to the communication server.

 

Exceptions
AsyncServiceError – Trying to run `connect` without initialize async service. A mat|r device can only be connected to the communication server after it has been initialized.
AsyncServiceError – Has been an exception in async service, in method ‘connect’. There is an error when connecting a mat|r device (connection error | server error).

 

void broker.async.subscribe(String canal, FunctionReference subscriptionCallback)

It subscribes the mat|r device to the communication server in the appropriate channel by passing a subscriptionCallback function as parameter. Such function will be executed when a message is received. The function must be referenced with the following syntax: @function(moduleName.functionName) and it should have a signature fulfilling 2 conditions: to return void and to have an only parameter of the one specified in the subscribed channel e.g. void functionName(MessageType msg)

 

Arguments
canal String: name of the channel it is subscribed to.
subscriptionCallback FunctionReference: function that will be called when receiving a message in the channel.

 

 

Exceptions
AsyncServiceError – AsyncServiceError – Trying to run `subscribe` without initialize async service. A mat|r device can only be subscribed to a channel after being initialized and connected.
AsyncServiceError – The channel ‘{channelName}’ doesn’t exist or you are not allowed to ‘subscribe’. The channel does not exist.
AsyncServiceError -Trying to run ‘subscribe’ without connection. A mat|r device can only be subscribed to a channel after being connected through the connect method.
ModuleNotFound – Module ‘moduleName’ not found in function argument of ‘broker.async.subscribe’ call. The module referenced in the argument ‘subscriptionCallback’ cannot be found.
FunctionNotFound – Function ‘functionName’ not found in module ‘moduleName’ in function argument of ‘broker.async.subscribe’ call. The function in module ‘moduleName’ referenced in the argument ‘subscriptionCallback’ cannot be found.
WrongFunctionSignature – Wrong signature in function argument ‘module.functionName()’ of ‘broker.async.subscribe’ call. Expected signature: ‘void function(Model aModel)’. The signature of the argument function ‘function’ does not coincide with the expected signature containing the definition of channel message type.
AsyncServiceError – Has been an exception in async service, in method ‘subscribe’. There is an error when subscribing a mat|r device to a channel (connection error | server error)

 

void broker.async.unsubscribe(String canal)

It unsubscribes the mat|r device from the communication server in the channel as specified in channel.

 

Arguments
canal String: name of the channel it is unsubscribed from.

 

 

Exceptions
AsyncServiceError – AsyncServiceError – Trying to run `unsubscribe` without initialize async service. A mat|r device can only be unsubscribed from a channel after being initialized and connected.
AsyncServiceError – The channel ‘{channelName}’ doesn’t exist or you are not allowed to ‘unsubscribe’. The channel does not exist.
AsyncServiceError -Trying to run ‘unsubscribe’ without connection. A mat|r device can only be unsubscribed from a channel after being connected through the connect method.
AsyncServiceError – Has been an exception in async service, in method ‘unsubscribe’. There is an error when trying to unsubscribe a mat|r device from a channel (connection error | server error).

 

void broker.async.publish(String canal, Model mensaje)

It publishes a message in the channel.

 

Arguments
canal String: name of the channel where the message is published in.
mensaje Model: it is the model that will be sent through the channel. The type of model must coincide with the type of message specified in the channel where publishing.

 

 

Exceptions
AsyncServiceError – AsyncServiceError – Trying to run `publish` without initialize async service. A mat|r device can only publish in a channel after being initialized and connected.
AsyncServiceError – The channel ‘{channelName}’ doesn’t exist or you are not allowed to ‘publish’. El canal no existe.
AsyncServiceError -Trying to run publish without connection. A mat|r device can only publish in a channel after being connected through the connect method.

 

void broker.async.disconnect()

It disconnects the mat|r device from the server.

NOTE: after disconnecting, all existing subscriptions are deleted.

 

Exceptions
AsyncServiceError – AsyncServiceError – Trying to run `disconnect` without initialize async service. A mat|r device can only be disconnected after being initialized.
AsyncServiceError – Has been an exception in async service, in method `disconnect`. There is an error when disconnecting a mat|r device from a channel (connection error | server error).

 

DYNAMIC ASYNC

 

PUBLIC DYNAMIC METHODS

 

ChannelData broker.async.createChannel(String name, Array deviceAccessList, String messageType, Map metadata)

It creates a dynamic channel with the name indicated in “name” and the message type in “messageType” that defines the method that will be used in the broker.async.publish () service to post messages on the new channel. It allows you to add a list of devices “deviceAccessList” so that they can publish and / or subscribe to it. The device that calls this method becomes the owner of the new channel.
NOTE: If the onChannelCreated event (ChannelData channelData) is defined, it is called on the devices that make up the DeviceAccess list which receives the metadata argument in the corresponding field of the ChannelData model.

 

Arguments
name String: name that the channel will have.
deviceAccessList Array: list of devices that will be added to the channel with publication and / or subscription permissions (it can be an empty list).
messageType String: name of the model that can be sent as a message through the channel.
metadata Map: additional information to associate with the channel.

 

Exceptions
AsyncServiceError – Has been an exception in async service ‘createChannel’. Error when creating a channel (Connection Error | Server Error).
AsyncServiceError – “Trying to run ‘createChannel’ without initialize async service. Error when attempting to create a channel without previous call to the service broker.async.initialize().
AsyncServiceError – ‘ {channelName}’ is already taken. The name that attempts to place on the channel has already been taken.
AsyncServiceError – “DeviceData is not valid, make sure you have loaded it from broker service getDevices(). “DeviceData” invalid.
AsyncServiceError – Device accessType value should be 0, 1, or 2. The accessType of the devices is different from 0,1 or 2.
AsyncServiceError – There must not be devices repeated in DeviceAccess list. There is a device repeated on the list.
ModelNotFound The model indicated as a message does not exist.

 

void broker.async.deleteChannel(String channelName)

Delete the channel that is named “channelName”.
NOTE: If the onChannelDeleted event (ChannelData channelData) is defined, it is called on the devices that were members of the channel, except for the owner of it.

 

Arguments
channelName String: name of the channel to be deleted.

 

Exceptions
AsyncServiceError – Trying to run ‘deleteChannel’ without initialize async service. Error when trying to delete a channel without first initializing the device.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘deleteChannel’. Error when trying to delete a channel that does not exist.
AsyncServiceError – Insufficient permission to delete channel. Error when trying to delete a channel without being the owner of it.
AsyncServiceError – Has been an exception in async service ‘deleteChannel’. Details: No internet connection. There is no internet connection

 

void broker.async.addDeviceToChannel(String channelName, DeviceAccess deviceAccess)

Add a device to a given channel.
NOTE: If the onChannelCreated event (ChannelData channelData) is defined, it is called on the device that is added to the channel.

 

Arguments
channelName String: channel name to which you add the device.
deviceAccess DeviceAccess: DeviceAccess of the device to be updated.

 

Exceptions
AsyncServiceError – Trying to run ‘addDeviceToChannel’ without initialize async service. Error when trying to add a device to a channel without having initialized async services.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘addDeviceToChannel’. Error when trying to add a device to a channel that does not exist.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices(). Error when using an invalid DeviceData.
AsyncServiceError – Device accessType value should be 0, 1, or 2. The accessType of the devices is different from 0,1 or 2.
AsyncServiceError – Insufficient permission to add device to channel. Insufficient permissions to add a device to the channel. Only the channel owner can do it.
AsyncServiceError – Device already exist in channel. The device is already in channel.

 

void broker.async.updateDeviceInChannel(String channelName, DeviceAccess device)

It updates the access settings of a device on a given channel.
NOTE: If the onChannelUpdated event (ChannelData channel, Integer accessType) is defined, it is called on the device that is updated on the channel.

 

Arguments
channelName String: name of the channel to which the device is added.
device DeviceAccess: DeviceAccess for the device on which you must perform the configuration update access.

 

Exceptions
AsyncServiceError – Trying to run updateDeviceInChannel without initialize async service. Error when trying to add a device to a channel without having initialized async services.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to updateDeviceInChannel. Error when trying to modify a device of a channel that does not exist.
AsyncServiceError – Insufficient permission to update device in channel. Insufficient permissions to update a channel device. Only the channel owner can do it.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices(). Error using an invalid DeviceData.
AsyncServiceError – Device accessType value should be 0, 1, or 2. The accessType of the device is different from 0, 1 or 2.
AsyncServiceError – The owner’s action type cannot be modified. It is not possible to modify the accessType of the channel owner. (Modify your permissions).
AsyncServiceError – Device doesn’t exist in channel: ‘{channelName}’. The device does not exist in channel.

 

void broker.async.replaceDevicesInChannel(String channelName, Array devices)

It replaces the devices of a given channel by the devices in the list provided as a parameter.
NOTES: If the onChannelCreated event (ChannelData channel) is defined, it is called on the devices that make up the DeviceAccess list that were added to the channel.
If the onChannelDeleted event (ChannelData channel) defined, it is called on the devices that were removed from the channel, except for the owner of it.

 

Arguments
channelName String: channel name.
devices DeviceAccess: list of devices (DeviceAccess) that will replace those found in the channel.

 

Exceptions
AsyncServiceError – Trying to run replaceDevicesInChannel without initialize async service. Error when trying to add a device to a channel without having initialized async services.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to replaceDevicesInChannel. Error when trying to add a device to a channel that does not exist.
AsyncServiceError – Insufficient permission to replace devices in channel. Insufficient permissions to replace channel devices. Only the channel owner can do it.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices(). Error when using an invalid DeviceData.
AsyncServiceError – Device accessType value should be 0, 1, or 2. The accessType of the device is different from 0,1 or 2.
AsyncServiceError – There must not be devices repeated in DeviceAccess list. There should not be repeated devices in the DevicesAccess list.

 

void broker.async.removeDeviceFromChannel(String channelName, DeviceData device)

Remove a given device from the indicated channel.
NOTE: If the onChannelDeleted event is defined, it is called on the device that was removed from the channel.

 

Arguments
channelName String: name of the channel to which the device is removed.
device DeviceAccess: data model of the device you want to remove.

 

Exceptions
AsyncServiceError – Trying to run ‘removeDeviceFromChannel’ without initialize async service. Error when trying to remove a device from a channel without initializing the device first.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘removeDeviceFromChannel’. Error when trying to remove a device from a channel that does not exist.
AsyncServiceError – Insufficient permission to delete channel. Error when trying to remove a device from a channel without being the owner of it.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices(). Error when using an invalid deviceData.
AsyncServiceError – The owner cannot be removed from the channel. Error when trying to remove the owner of the channel. The owner can not be removed.
AsyncServiceError – Has been an exception in async service ‘removeDeviceFromChannel’ . Details: No internet connection. There is no internet connection.

 

Array broker.async.getChannels()

It gets a list of all the channels the device is a member of. It only returns dynamic channels.

 

Exceptions
AsyncServiceError – Trying to run ‘getChannels’ without initialize async service. Error when trying to get the channels without initializing the device first.
AsyncServiceError – Has been an exception in async service ‘getChannels’ . Details: No internet connection. There is no internet connection.

 

Array broker.async.getDevices()

It gets a list of all the devices that have been initialized in the application.

 

Exceptions
AsyncServiceError – Trying to run ‘getChannels’ without initialize async service. Error when trying to get the channels without initializing the device first.
AsyncServiceError – Has been an exception in async service ‘getChannels’ . Details: No internet connection. There is no internet connection.

 

ASYNC MODULE

The Async module allows you to define different events that are executed on devices when updating their states on a channel. The events to be defined are the following:

void onChannelCreated(ChannelData channelCreated)
If it is declared, it is called when:
The device is included in a new channel.
The device is added to an existing channel.

void onChannelUpdated(ChannelData channelUpdated, Integer editedPermission)
If it is declared, it is called at the moment in which the owner of the channel modifies the permissions of the device in that channel.

void onChannelDeleted(ChannelData deletedChannel)
If declared, it is called when:
The owner of the channel eliminates it.
The owner of the channel removes the device from it.

Module asyncModule {
     void  onChannelCreated (ChannelData channelCreated) {
     
      }

     void  onChannelUpdated (ChannelData channelUpdated, Integer editedPermission) {
     
      }

     void  onChannelDeleted (ChannelData deletedChannel) {
     
      }
}