MQTT Subscriber

This adapter allows to subscribe to a topic in an MQTT broker.

The MQTT protocol provides a simple method for sending messages via a publish/subscribe model. This makes it particularly suitable for messaging in the internet of things environment, such as low-power sensors or mobile devices like telephones, embedded computers or micro-controllers.

Note:

The MQTT Subscriber is mostly used in combination with the MQTT Publisher.

Properties

Operation

Defines the operation executed by the adapter.

Possible values:

Subscribe: Enables subscribing to a topic in an MQTT broker.
Unsubscribe: Enables unsubscribing to a topic in an MQTT broker.

Parameters

`Adapter`	Adapter main class (do not change!) Possible values: de.softproject.integration.adapter. mqtt.MqttSubscriberAdapter: Main class (default)
`Alias`	Broker alias Possible values: Any string The alias can be defined within the configuration file `mqttconfig.xml` as attribute of the element `Broker`.
`ClientId`	Identifier for the client that subscribes to the broker. Possible values: If the Client ID is defined in the configuration file `mqttconfig.xml`: Any string If the Client ID is not defined in the configuration file `mqttconfig.xml`: UUID The Client ID can be defined within the configuration file `mqttconfig.xml` for each broker in the `ClientId` element.
`clientTimeout`	Timeout for ONLINE_ON_DEMAND connections (for the operation `Subscribe`). If `ConnectionMode` differs from `ONLINE_ON_DEMAND`, `ClientTimeout` is not taken into account. Possible values: Integer greater than `0`
`connectionMode`	Connection mode selected to create the Client. Depending on the selected value, the client connection is held or disconnected after a certain time (`ClientTimeout`). Possible values: `ONLINE_ON_DEMAND`: The `ClientTimeout` parameter is required to configure the client. `ALWAYS_ONLINE_ON_FIRST_PUBLISH`: The client stays connected as soon as an initial publishing happens. Therefore, the `ClientTimeout` parameter is not required. This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`stateful`	Defines if the state between client and broker is stateful. Possible values: `true` / `false` This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`keystorePath`	Path to the keystore. If no SSL/TLS configuration is required to connect to the broker, this parameter value may be empty. Possible values: File system path This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`keystorePassword`	Password for the keystore specified for `KeystorePath`. Possible values: Any string This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`Topic`	Name of the topic that the client subscribes to. Possible values: Any string The topic can be defined within the configuration file `mqttconfig.xml` for each broker in the attribute `filter` of the element `Topic`.
`server`	Protocol, host and port to connect client and broker. Possible values: `tcp://hostname:port`: If no SSL/TLS connection is used. `ssl://hostname:port`: If a SSL/TLS connection is used. This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`InputFormat`	Input format of the adapter Possible values: `BYTES` `BASE64_STRING` `BASE64_XML`
`loginUsername`	Username that is used to connect to a broker that requires credentials. Possible values: Username This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`loginPassword`	Password that is used to connect to a broker that requires credentials. Possible values: Password This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`QoS`	Quality of Service, for receiving messages when subscribing to a topic. Possible values: `AT_MOST_ONCE` `AT_LEAST_ONCE` (default) `EXACTLY_ONCE` This parameter is not required if `alias` and `clientId` are defined in the configuration file or the values for `alias` and `clientId` have already been used to establish a connection.
`process`	Path to the process that is executed each time a message of the subscribed topic is received. Possible values: Process path in the format `x4db://User/process.wrf`

Status values

`1`	The adapter operation was executed successfully.
`-1`	An error occurred during connection establishment, disconnection, publishing or subscription.

Input

The adapter expects no input document.

Output

The output is the same as the input.

Configuration file

To define broker, client, SSL/TLS configurations etc. a configuration file with a specified structure can be used, which is loaded at server startup. The configuration file mqttconfig.xml must be stored under the server path X4DB/0. If broker and client are defined in the configuration file, then only the values for alias and cliendId have to be specified in the adapter parameters.

The file contains the following information:

KeyStore

Path and password of the keystore that is used to establish a SSL connection to a broker. If this optional element is not defined, a trust manager is created that accepts all certificates.

When specifying the path, both absolute and relative paths to X4DB/0 are allowed.

Example:

Relative path specification

XML

<RootElement>
    <KeyStore password="p4ssw0rd">keystore.jks</KeyStore>
</RootElement>

Absolute path specification

XML

<RootElement>
    <KeyStore password="p4ssw0rd">C:\Path\To\Keystore\keystore.jks</KeyStore>
</RootElement>

Broker

MQTT server

Relevant information is embedded in the attribute alias. This attribute must be unique.
The broker contains the following elements:

Server: Broker URL; The protocols TSL and TCP are supported.
- ssl://host:port : The broker is connected via TSL protocol.
- Host is replaced by the host server and port by the port server.
- tcp://host:port : The broker is connected via TCP protocol (without SSL encryption).
  Host is replaced by the host server and port by the port server.
ClientId: Unique client ID with the following attributes:
- mode: Type of the connection
  - ALWAYS_ONLINE_ON_STARTUP (default): Adapter connects at server startup and holds connection all the time.
  - ALWAYS_ONLINE_ON_FIRST_PUBLISH : The connection is established at the first request (Publish) and is held all the time.
  - ONLINE_ON_DEMAND : The adapter connects if no connection exists and has an additional timeout attribute that is only valid in this mode. The attribute disconnects the connection after the specified time (in seconds) after the last message was sent.
  If mode has an invalid value or is empty, the default value ALWAYS_ONLINE_ON_STARTUP is presumed.
- timeout: Timeout in seconds. This attribute is only valid for the mode ONLINE_ON_DEMAND and disconnects the connection after a specified time (in seconds) after the last message was sent.
  If timeout is empty, the default value of 20 seconds is presumed.

Topic

Topic that can be subscribed to to receive the published message. It has the following attributes:

filter: Name of the topic filter
qos: Quality of service
- AT MOST ONCE : The message will be delivered only once or not at all. There will be no notification when the message has been delivered.
- AT LEAST ONCE : The message is always delivered at least once. If the sender does not receive a notification, the message with the DUP flag is delivered again until a notification is received.
- EXACTLY ONCE : The message must be stored locally at the sender and receiver until it has been processed.
If the attribute qos is not defined, the default value is AT_LEAST_ONCE.
For each topic a process is defined that is executed when a message is received. The element Process has the following attributes:

url: Process path in the format x4db://User/process.wrf

Sample configuration

XML

<?xml version='1.0' encoding='UTF-8'?>
<RootElement>
	<!-- Both, relative and absolute paths to X4DB/0 are allowed -->
	<KeyStore password="password">C:/Users/MaxMustermann/Documents/MQTT/Keystore/application.keystore</KeyStore>
	<Broker alias="Mosquitto_MQTT">
		<Server>ssl://localhost:8883</Server>
		<ClientId mode="ALWAYS_ONLINE_ON_STARTUP">C1</ClientId>
		<ClientId mode="ALWAYS_ONLINE_ON_FIRST_PUBLISH">C2</ClientId>
		<ClientId timeout="40" mode="ONLINE_ON_DEMAND">C3</ClientId>
		<ClientId timeout="20" mode="ONLINE_ON_DEMAND">C4</ClientId>
		<Topic filter="topic/action1" qos="AT_LEAST_ONCE">
			<Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic1.wrf"/>
		</Topic>
		<Topic filter="topic/action2" qos="AT_MOST_ONCE">
			<Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic2.wrf"/>
		</Topic>
		<Topic filter="topic/action1" qos="EXACTLY_ONCE">
			<Process url="x4db://1/X4Experience/ESB/3-Reference/1-AdapterSuites/X4MQTTAdapter/Processes/TopicProcesses/ProcessTopic3.wrf"/>
		</Topic>
	</Broker>
</RootElement>