Async

A través de los servicios broker.async.*, se tiene acceso a funciones relacionadas con intercambio de mensajes asíncronos entre distintos Mat|r Devices. Recuerda que para crear este servicio primero necesitas crear un Channel.

Mat|r Device:
Un Mat|r Device puede ser una Mat|r App corriendo en un broker particular o un IoT Device configurado desde la Plataforma.

MÉTODOS PÚBLICOS

void broker.async.initialize()

Realiza las configuraciones correspondientes en el Mat|r Device para la comunicación a través de canales. Esta llamada es requerida antes de la llamada al método connect. El servicio es inicializado una única vez por ejecución de la app, las siguientes llamadas son ignoradas.
NOTA: En caso que el device ya hubiese sido inicializado con metadata la misma quedará sin modificaciones.

Excepciones
AsyncServiceError – Has been an exception in async service ‘initialize’.	Error al inicializar un Mat\|r Device (Connection Error \| Server Error)

void broker.async.initialize(Map metadata)

Inicializa el Mat|r Device asociando información adicional: metadata, el cual podría ser null, o vacio.

Argumentos
metadata	Map<String>: informacion adicional para asociar al Mat\|r Device.

Excepciones
AsyncServiceError – Has been an exception in async service ‘initialize’.	Error al inicializar un Mat\|r Device (Connection Error \| Server Error)

void broker.async.connect()

Conecta el Mat|r Device con el server de comunicación.

Excepciones
AsyncServiceError – Trying to run `connect` without initialize async service.	Un Matr Device solo puede conectarse al server de comunicación luego de ser inicializado.
AsyncServiceError – Has been an exception in async service, in method ‘connect’.	Error al conectar un Matr Device (Connection Error \| Server Error)

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

Suscribe el Mat|r Device con el server de comunicación en el canal indicado, pasando como parámetro una función subscriptionCallback que se ejecutará cuando se reciba un mensaje. Para referenciar la función debe utilizarse la sintaxis: @function(nombreModulo.nombreFuncion) y la misma debe contar con una firma que cumpla 2 condiciones: retornar void, y tener un único parámetro del tipo especificado en el canal al que se subscribe. Ej: void nombreFuncion(MessageType msg)

Argumentos
canal	String: nombre del canal al que se subscribe.
subscriptionCallback	FunctionReference: función que será llamada cuando llegue un mensaje al canal.

Excepciones
AsyncServiceError – AsyncServiceError – Trying to run `subscribe` without initialize async service.	Un Mat\|r Device solo puede suscribirse a un canal luego de ser inicializado y conectado.
AsyncServiceError – The channel ‘{channelName}’ doesn’t exist or you are not allowed to ‘subscribe’.	El canal no existe.
AsyncServiceError -Trying to run ‘subscribe’ without connection.	Un Mat\|r device solo puede suscribirse a un canal luego de haberse conectado a través del método connect.
ModuleNotFound – Module ‘moduleName’ not found in function argument of ‘broker.async.subscribe’ call.	No se encuentra el módulo referenciado en el argumento ‘subscriptionCallback’.
FunctionNotFound – Function ‘functionName’ not found in module ‘moduleName’ in function argument of ‘broker.async.subscribe’ call.	No se encuentra la función dentro del módulo ‘moduleName’ referenciado en el argumento ‘subscriptionCallback’.
WrongFunctionSignature – Wrong signature in function argument ‘module.functionName()’ of ‘broker.async.subscribe’ call. Expected signature: ‘void function(Model aModel)’.	La firma de la función del argumento ‘function’ no coincide con una firma esperada con la definición del tipo de mensaje del canal.
AsyncServiceError – Has been an exception in async service, in method ‘subscribe’.	Error al suscribir un Mat\|r Device a un canal (Connection Error \| Server Error)

void broker.async.unsubscribe(String canal)

Elimina la suscripción del Mat|r Device con el server de comunicación en el canal indicado en canal.

Argumentos
canal	String: nombre del canal al que se de-subscribe.

Excepciones
AsyncServiceError – AsyncServiceError – Trying to run `unsubscribe` without initialize async service.	Un Mat\|r Device solo puede eliminar una suscripción de un canal luego de ser inicializado y conectado.
AsyncServiceError – The channel ‘{channelName}’ doesn’t exist or you are not allowed to ‘unsubscribe’.	El canal no existe.
AsyncServiceError -Trying to run ‘unsubscribe’ without connection.	Un Mat\|r device solo puede eliminar una suscripción de un canal luego de haberse conectado a través del método connect.
AsyncServiceError – Has been an exception in async service, in method ‘unsubscribe’.	Error al intentar eliminar una suscripción de un Mat\|r Device a un canal (Connection Error \| Server Error)

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

Publica un mensaje en el canal.

Argumentos
canal	String: nombre del canal al que se publica.
mensaje	Model: Es el modelo que se enviará a través del canal. El tipo del modelo deberá coincidir con el tipo de mensaje especificado en el canal al que se publica.

Excepciones
AsyncServiceError – AsyncServiceError – Trying to run `publish` without initialize async service.	Un Mat\|r Device solo puede publicar en un canal luego de ser inicializado y conectado.
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.	Un Mat\|r device solo puede publicar en un canal luego de haberse conectado a través del método connect.

void broker.async.disconnect()

Desconecta al Matr Device del servidor.
NOTA: Luego de desconectarse se borran todas las suscripciones existentes.

Excepciones
AsyncServiceError – AsyncServiceError – Trying to run `disconnect` without initialize async service.	Un Mat\|r Device solo puede desconectar luego de ser inicializado.
AsyncServiceError – Has been an exception in async service, in method `disconnect`.	Error al desconectar un Mat\|r Device de un canal (Connection Error \| Server Error)

ASYNC DINÁMICO

MÉTODOS PÚBLICOS DINÁMICOS

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

Crea un canal dinámico con el nombre indicado en “name” y el tipo de mensaje en “messageType” que define el tipo que se utilizará en el servicio broker.async.publish() para publicar mensajes en el canal a crear. Permite agregar una lista de dispositivos “deviceAccessList” para que puedan publicar y/o suscribirse en el mismo. El device que llama a este método se convierte en el dueño del nuevo canal.
NOTA: De estar definido, el evento onChannelCreated(ChannelData channelData) es llamado en los dispositivos que componen la lista de DeviceAccess, que reciben el argumento metadata en el campo correspondiente del modelo ChannelData.

Argumentos
name	String: nombre que tendrá el canal.
deviceAccessList	Array: lista de dispositivos que serán agregados al canal con permisos de publicación y/o suscripción (puede ser una lista vacía).
messageType	String: nombre del modelo que podrá ser enviado como mensaje a través del canal.
metadata	Map: información adicional para asociar al canal.

Excepciones
AsyncServiceError – Has been an exception in async service ‘createChannel’.	Error al crear un canal (Connection Error \| Server Error).
AsyncServiceError – “Trying to run ‘createChannel’ without initialize async service.	Error al intentar crear un canal sin previa llamada al servicio broker.async.initialize().
AsyncServiceError – ‘ {channelName}’ is already taken.	El nombre que se intenta colocar al canal ya fue tomado.
AsyncServiceError – “DeviceData is not valid, make sure you have loaded it from broker service getDevices().	“DeviceData” invalido.
AsyncServiceError – Device accessType value should be 0, 1, or 2.	El accessType de los dispositivos es distinto de 0, 1 o 2.
AsyncServiceError – There must not be devices repeated in DeviceAccess list.	Hay un dispositivo repetido en la lista.
ModelNotFound	El modelo indicado como mensaje no existe.

void broker.async.deleteChannel(String channelName)

Borra el canal que tiene por nombre “channelName”.
NOTA: De estar definido, el evento onChannelDeleted(ChannelData channelData) es llamado en los dispositivos que eran miembros del canal, exceptuando al dueño del mismo.

Argumentos
channelName	String: nombre del canal a borrar.

Excepciones
AsyncServiceError – Trying to run ‘deleteChannel’ without initialize async service.	Error al intentar borrar un canal sin inicializar primero el dispositivo.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘deleteChannel’.	Error al intentar borrar un canal que no existe.
AsyncServiceError – Insufficient permission to delete channel.	Error al intentar borrar un canal sin ser el dueño(owner) del mismo.
AsyncServiceError – Has been an exception in async service ‘deleteChannel’. Details: No internet connection.	No se tiene conexión a internet.

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

Agrega un device a un canal dado.
NOTA: De estar definido, el evento onChannelCreated(ChannelData channelData) es llamado en el dispositivo que es agregado al canal.

Argumentos
channelName	String: nombre del canal al que se le agrega el dispositivo.
deviceAccess	DeviceAccess: DeviceAccess del dispositivo que se quiere actualizar.

Excepciones
AsyncServiceError – Trying to run ‘addDeviceToChannel’ without initialize async service.	Error al intentar agregar un dispositivo a un canal sin haber inicializado los servicios de async.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘addDeviceToChannel’.	Error al intentar agregar un dispositivo a un canal que no existe.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices().	Error al utilizar un DeviceData inválido.
AsyncServiceError – Device accessType value should be 0, 1, or 2.	El accessType del dispositivo es distinto de 0,1 o 2.
AsyncServiceError – Insufficient permission to add device to channel.	Permisos insuficientes para agregar un dispositivo al canal. Solo el dueño del canal puede hacerlo.
AsyncServiceError – Device already exist in channel.	El dispositivo ya se encuentra en el canal.

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

Actualiza la configuración de acceso de un dispositivo en un canal dado.
NOTA: De estar definido, el evento onChannelUpdated(ChannelData channel, Integer accessType) es llamado en el dispositivo que es actualizado del canal.

Argumentos
channelName	String: nombre del canal donde se encuentra el dispositivo a actualizar.
device	DeviceAccess: DeviceAccess del dispositivo que se quiere actualizar.

Excepciones
AsyncServiceError – Trying to run updateDeviceInChannel without initialize async service.	Error al intentar agregar un dispositivo a un canal sin haber inicializado los servicios de async.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to updateDeviceInChannel.	Error al intentar modificar un dispositivo de un canal que no existe.
AsyncServiceError – Insufficient permission to update device in channel.	Permisos insuficientes para actualizar un dispositivo del canal. Solo el dueño del canal puede hacerlo.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices().	Error al utilizar un DeviceData inválido.
AsyncServiceError – Device accessType value should be 0, 1, or 2.	El accessType del dispositivo es distinto de 0,1 o 2.
AsyncServiceError – The owner’s action type cannot be modified.	No es posible modificar el accessType del dueño del canal. (Modificar sus permisos).
AsyncServiceError – Device doesn’t exist in channel: ‘{channelName}’.	El dispositivo no existe en el canal.

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

Reemplaza los dispositivos de un canal dado por los dispositivos de la lista brindada como parámetro.
NOTAS: De estar definido, el evento onChannelCreated(ChannelData channel) es llamado en los dispositivos que componen la lista de DeviceAccess que fueron agregados al canal.
De estar definido, el evento onChannelDeleted(ChannelData channel) es llamado en los dispositivos que fueron removidos del canal, exceptuando al dueño del mismo.

Argumentos
channelName	String: nombre del canal donde se encuentra el dispositivo a actualizar.
devices	DeviceAccess: lista de dispositivos (DeviceAccess) que van a reemplazar a los que se encuentran en el canal.

Excepciones
AsyncServiceError – Trying to run replaceDevicesInChannel without initialize async service.	Error al intentar agregar un dispositivo a un canal sin haber inicializado los servicios de async.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to replaceDevicesInChannel.	Error al intentar agregar un dispositivo a un canal que no existe.
AsyncServiceError – Insufficient permission to replace devices in channel.	Permisos insuficientes para reemplazar los dispositivos del canal. Solo el dueño del canal puede hacerlo.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices().	Error al utilizar un DeviceData inválido.
AsyncServiceError – Device accessType value should be 0, 1, or 2.	El accessType del dispositivo es distinto de 0,1 o 2.
AsyncServiceError – There must not be devices repeated in DeviceAccess list.	No deben existir dispositivos repetidos en la lista de DevicesAccess.

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

Remueve un dispositivo dado del canal indicado.
NOTA: De estar definido, el evento onChannelDeleted es llamado en el dispositivo que fue removido del canal.

Argumentos
channelName	String: nombre del canal al que se le remueve el dispositivo.
device	DeviceAccess: modelo de datos del dispositivo que se quiere remover.

Excepciones
AsyncServiceError – Trying to run ‘removeDeviceFromChannel’ without initialize async service.	Error al intentar remover un dispositivo de un canal sin inicializar primero el dispositivo.
AsyncServiceError – The channel ‘channelName’ does not exist or you are not allowed to ‘removeDeviceFromChannel’.	Error al intentar remover un dispositivo de un canal que no existe.
AsyncServiceError – Insufficient permission to delete channel.	Error al intentar remover un dispositivo de un canal sin ser el dueño(owner) del mismo.
AsyncServiceError – DeviceData is not valid, make sure you have loaded it from broker service getDevices().	Error al utilizar un dispositivo inválido.
AsyncServiceError – The owner cannot be removed from the channel.	Error al intentar remover al dueño del canal. Éste no puede ser removido.
AsyncServiceError – Has been an exception in async service ‘removeDeviceFromChannel’ . Details: No internet connection.	No se tiene conexión a internet.

Array broker.async.getChannels()

Obtiene una lista de todos los canales de los que es miembro el dispositivo. Sólo retorna canales dinámicos.

Excepciones
AsyncServiceError – Trying to run ‘getChannels’ without initialize async service.	Error al intentar obtener los canales sin inicializar primero el dispositivo.
AsyncServiceError – Has been an exception in async service ‘getChannels’. Details: No internet connection.	No se tiene conexión a internet.

Array broker.async.getDevices()

Obtiene una lista de todos los dispositivos que han sido inicializados en la aplicación.

Excepciones
AsyncServiceError – Trying to run ‘getChannels’ without initialize async service.	Error al intentar obtener los canales sin inicializar primero el device.
AsyncServiceError – Has been an exception in async service ‘getChannels’. Details: No internet connection.	No se tiene conexión a internet.

MÓDULO ASYNC

El módulo Async permite definir diferentes eventos que son ejecutados en los dispositivos al momento de actualizar sus estados en un canal. Los eventos a definir son los siguientes:

void onChannelCreated(ChannelData channelCreated)
Si está declarado, es llamado cuando:
Se incluye al dispositivo en un canal nuevo.
Se agrega al dispositivo en un canal existente.

void onChannelUpdated(ChannelData channelUpdated, Integer editedPermission)
Si está declarado es llamado en el momento en que el dueño del canal modifica los permisos del dispositivo en dicho canal.

void onChannelDeleted(ChannelData deletedChannel)
Si está declarado es llamado cuando:
El dueño del canal elimina el mismo.
El dueño del canal elimina al dispositivo del mismo.

Module asyncModule {
     void  onChannelCreated (ChannelData channelCreated) {
     
      }

     void  onChannelUpdated (ChannelData channelUpdated, Integer editedPermission) {
     
      }

     void  onChannelDeleted (ChannelData deletedChannel) {
     
      }
}