MQTT Subscriber

Dieser Adapter ermöglicht das Abonnieren eines Topics in einem MQTT-Broker.

Das MQTT-Protokoll bietet eine einfache Methode zur Nachrichtenübermittlung über ein Publish/Subscribe-Modell. Damit eignet es sich besonders für die Nachrichtenübermittlung im Umfeld des Internet der Dinge, wie z. B. bei Sensoren mit niedriger Leistung oder mobilen Geräten wie Telefonen, eingebetteten Computern oder Mikrocontrollern.

Hinweis:

Der MQTT Subscriber wird meist in Verbindung mit dem MQTT Publisher verwendet.

Eigenschaften (Properties)

Operation

Vom Adapter ausgeführte Operation

Mögliche Werte:

Subscribe: Ermöglicht das Abonnieren eines Topics in einem MQTT-Broker.
Unsubscribe: Ermöglicht die Abmeldung von einem Topic in einem MQTT-Broker.

Parameter

`Adapter`	Adapter-Hauptklasse (nicht verändern!) Mögliche Werte: de.softproject.integration.adapter. mqtt.MqttSubscriberAdapter: Hauptklasse (Standard)
`Alias`	Broker-Alias Mögliche Werte: Beliebige Zeichenkette Der Alias kann innerhalb der Konfigurationsdatei `mqttconfig.xml` als Attribut des Elements `Broker` definiert werden.
`ClientId`	Bezeichner für den Client, der den Broker abonniert Mögliche Werte: Falls die Client ID in der Konfigurationsdatei `mqttconfig.xml` definiert ist: beliebige Zeichenkette Falls die Client ID nicht in der Konfigurationsdatei `mqttconfig.xml` definiert ist: UUID Die Client ID kann innerhalb der Konfigurationsdatei `mqttconfig.xml` für jeden Broker im Element `ClientId` definiert werden.
`clientTimeout`	Timeout für ONLINE_ON_DEMAND-Verbindungen (für die Operation `Subscribe`). Wenn `ConnectionMode` von `ONLINE_ON_DEMAND` abweicht, wird `ClientTimeout` nicht berücksichtigt. Mögliche Werte: Ganzzahl größer als `0`
`connectionMode`	Verbindungsmodus, der zum Erstellen des Clients ausgewählt wurde. Abhängig vom gewählten Wert bleibt die Client-Verbindung erhalten oder wird nach einer bestimmten Zeit wieder getrennt (`ClientTimeout`). Mögliche Werte: `ONLINE_ON_DEMAND`: Der Parameter `ClientTimeout` wird benötigt, um den Client zu konfigurieren. `ALWAYS_ONLINE_ON_FIRST_PUBLISH`: Der Client bleibt verbunden, sobald eine erste Veröffentlichung erfolgt. Daher wird der Parameter `ClientTimeout` nicht benötigt. Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`stateful`	Legt fest, ob der Zustand zwischen dem Client und dem Broker zustandsorientiert ist. Mögliche Werte: `true` / `false` Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`keystorePath`	Pfad zum Keystore. Wenn keine SSL/TLS-Konfiguration benötigt wird, um eine Verbindung zum Broker herzustellen, dann kann der Parameterwert leer sein. Mögliche Werte: Dateipfad Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`keystorePassword`	Passwort zum für `KeystorePath` angegebenen Keystore. Mögliche Werte: Beliebige Zeichenkette Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`Topic`	Name des Topics, das der Client abonniert Mögliche Werte: Beliebige Zeichenkette Das Topic kann innerhalb der Konfigurationsdatei `mqttconfig.xml` für jeden Broker im Attribut `filter` des Elements `Topic` definiert werden.
`server`	Protokoll, Host und Port für die Verbindung vom Client zum Broker. Mögliche Werte: `tcp://hostname:port`: Falls keine SSL/TLS-Verbindung verwendet wird. `ssl://hostname:port`: Falls eine SSL/TLS-Verbindung verwendet wird. Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`InputFormat`	Input-Format des Adapters Mögliche Werte: `BYTES` `BASE64_STRING` `BASE64_XML`
`loginUsername`	Username, der verwendet wird, um eine Verbindung zu einem Broker herzustellen, der Zugangsdaten verlangt. Mögliche Werte: Benutzername Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`loginPassword`	Passwort, das verwendet wird, um eine Verbindung zu einem Broker herzustellen, der Zugangsdaten verlangt. Mögliche Werte: Passwort Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`QoS`	Quality of Service, für den Nachrichtenempfang beim Abonnement eines Topics. Mögliche Werte: `AT_MOST_ONCE` `AT_LEAST_ONCE` (Standard) `EXACTLY_ONCE` Dieser Parameter wird nicht benötigt, wenn `alias` und `clientId` in der Konfigurationsdatei definiert sind oder die Werte für `alias` und `clientId` bereits verwendet wurden, um eine Verbindung herzustellen.
`Process`	Pfad zum Prozess, der jedes Mal ausgeführt wird, wenn eine Nachricht des abonnierten Topics empfangen wurde Mögliche Werte: Prozess-Pfad im Format `x4db://User/process.wrf`

Statuswerte

`1`	Die Operation wurde erfolgreich ausgeführt.
`-1`	Es gab einen Fehler während des Verbindungsaufbaus, der Trennung der Verbindung, der Veröffentlichung oder dem Abonnieren

Input

Der Adapter erwartet kein Input-Dokument.

Output

Die Ausgabe entspricht dem Input.

Konfigurationsdatei

Um Broker, Client, SSL/TLS-Konfigurationen usw. zu definieren, kann eine Konfigurationsdatei mit einer festgelegten Struktur verwendet werden, die beim Serverstart geladen wird. Die Konfigurationsdatei mqttconfig.xml muss unter dem Serverpfad X4DB/0 abgelegt werden. Wenn Broker und Client in der Konfigurationsdatei definiert sind, dann müssen in den Adapterparametern nur die Werte für alias und cliendId angegeben werden.

Die Datei enthält folgende Informationen:

KeyStore

Pfad und Passwort des Keystores, der verwendet wird, um eine SSL-Verbindung zum Broker aufzubauen. Ist dieses optionale Element nicht angegeben, wird ein Trust-Manager angelegt, der alle Zertifikate annimmt.

Bei der Pfadangabe können sowohl absolute als auch relative Pfade zum Verzeichnis X4DB/0 angegeben werden.

Beispiel:

Relative Pfadangabe

XML

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

Absolute Pfadangabe

XML

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

Broker

MQTT-Server

Relevante Informationen werden im Attribut alias eingebettet. Dieses Attribut muss eindeutig sein.
Der Broker enthält folgende Elemente:

Server: Broker-URL; Die Protokolle TSL und TCP werden unterstützt.
- ssl://host:port : Die Verbindung zum Broker findet über das TSL-Protokoll statt.
- Host wird durch den Host Server und Port durch den Port Server ersetzt.
- tcp://host:port : Die Verbindung zum Broker findet über das TCP-Protokoll (ohne SSL-Verschlüsselung) statt.
  Host wird durch den Host Server und Port durch den Port Server ersetzt.
ClientId: Eindeutige Client-ID mit folgenden Attributen:
- mode: Art der Verbindung
  - ALWAYS_ONLINE_ON_STARTUP (Standard): Der Adapter verbindet sich beim Server-Start und hält die Verbindung die ganze Zeit aufrecht
  - ALWAYS_ONLINE_ON_FIRST_PUBLISH : Die Verbindung wird bei der ersten Anfrage (Publish) aufgebaut und die ganze Zeit aufrechterhalten
  - ONLINE_ON_DEMAND : Der Adapter verbindet sich, wenn noch keine Verbindung besteht und hat ein zusätzliches Attribut timeout, das lediglich in diesem Modus gültig ist. Das Attribut trennt die Verbindung nach der angegebenen Zeit (in Sekunden) nachdem die letzte Nachricht versendet wurde.
  Hat mode einen ungültigen Wert oder ist leer, wird der Standard-Wert ALWAYS_ONLINE_ON_STARTUP angenommen.
- timeout: Timeout in Sekunden. Dieses Attribut ist nur für den Verbindungstyp ONLINE_ON_DEMAND gültig und trennt die Verbindung nach der angegebenen Zeit (in Sekunden) nachdem die letzte Nachricht versendet wurde.
  Wenn timeout leer ist, wird der Standard-Wert von 20 Sekunden angenommen.

Topic

Topic das abonniert werden kann, um die veröffentlichte Nachricht zu erhalten. Es hat folgende Attribute:

filter: Name des Topic-Filters
qos: Quality of service
- AT MOST ONCE : Die Nachricht wird höchstens ein Mal oder kein einziges Mal zugestellt. Es erfolgt keine Benachrichtigung, wenn die Zustellung erfolgt ist.
- AT LEAST ONCE : Die Nachricht wird immer mindestens ein Mal zugestellt. Erhält der Sender keine Benachrichtigung, wird die Nachricht mit dem DUP-Flag erneut zugestellt, bis eine Benachrichtigung empfangen wurde.
- EXACTLY ONCE : Die Nachricht muss beim Sender und beim Empfänger lokal gespeichert werden, bis diese verarbeitet wurde.
Ist das Attribut qos nicht angegeben, ist der Standard-Wert AT_LEAST_ONCE.
Für jedes Topic wird ein Prozess definiert, der nach Eingang der Nachricht ausgeführt werden soll. Das Element Process hat folgende Attribute:

url: Prozess-Pfad im Format x4db://User/process.wrf

Beispiel-Konfiguration

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>