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).