Messaging Module

The Structr Messaging-Engine module provides a generic abstraction of a publish and subscription model based on topics.

The basic idea is that a MessageClient acts as a Connector to a broker or an abstraction of such and provides the ablity to send messages and to (un)subscribe to topics. Its counterpart is the MessageSubscriber, which relates to MessageClients and is triggered when a message for the subscribed topic is received by the client. During this process the subscriber evaluates a script supplied as one of its attributes and has access to the message’s topic and content in that context.
This allows for flexible and powerful interaction with Structr’s core functionality.

Apart from the basic abstraction of a MessageClient, the module provides different implementations that act as connectors to their respective technology.
As such the module provides a MQTTClient and a KafkaClient as spezialized implementations.

Details on how to setup these entities are found in their respective documentation.

MessageClient

MessageClient is the base abstraction of a client connecting to a broker in the Messaging-Engine Module module.
The basic capabilities of the client include the following methods

Name	Parameters	Description
`sendMessage`	String topic, String message	Publishes a message on given topic
`subscribeTopic`	String topic	Subscribes the given topic. Invoked automatically by MessageSubscribers.
`unsubscribeTopic`	String topic	Unsubscribes the given topic. Invoked automatically by MessageSubscribers.

And the following properties

Name	Type	Description
`subscribers`	Array of MessageSubscribers	A list of all related subscribers.

KafkaClient

KafkaClient is a specialization of the MessageClient included in the Messaging-Engine Module module.

The KafkaClient connects to a Kafka broker and handles the publication as well as subscription of messages.

KafkaClient extends MessageClient and provides the following additional properties.

Name	Type	Description
`servers`	Array of String	List of kafka brokers to connect to. Format: `IP:PORT`. E.g.: ‘localhost:9092’

Note: The consumer used in the implementation expects String-based message contents.

MQTTClient

MQTTClient is a specialization of the MessageClient included in the Messaging-Engine Module module.

The MQTTClient connects to a MQTT broker and handles the publication as well as subscription of messages.

MQTTClient extends MessageClient and provides the following additional properties.

Name	Type	Description
`protocol`	String	Protocol used for the MQTT connections. Default: `tcp://`
`url`	String	The URL for the MQTT connection
`port`	Integer	The port to connect to
`qos`	Integer	Quality of Service Range: 0~2
`isEnabled`	Boolean	A boolean value that indicates whether this MQTTClient is enabled (should connect to the broker)
`isConnected`	Boolean	A boolean value that indicates whether this MQTTClient is connected to the broker

MessageSubscriber

MessageSubscriber is a generic abstraction of a subscriber included in the Messaging-Engine Module module.
It can attach to any kind of MessageClient and will subscribe on that client with the specified topic.
If the client receives a message on given topic, a callback will be made to the subscriber and the message will be evaluated in a scripting context that is specified in the subscribers callback attribute.

The following properties can be configured for the subscriber:

Name	Type	Description
`clients`	Array of MessageClient	A list of all related clients that will be subscribed on.
`topic`	String	The topic that will be subscribed
`callback`	String	Specifies a script that is evaluated upon the reception of a relevant message.

Note: Instead of using a specific topic, it is also possible to use * as a wildcard subscription.
The default scripting context is StructrScript and the message’s content is injected as well and available via retrieve() under the following attributes.

Key	Description
`topic`	The topic the message was sent in.
`message`	The message’s content.