Einführung: Phase 1.

Der Eingangsagent AMQP kann Daten von einer Message Queue eines Servers entgegennehmen, der das Advanced Message Queuing Protocol implementiert. Dieses Protokoll ist plattformunabhängig und wird von einer großen Zahl von Systemen unterstützt. Die meisten JMS-Server haben bereits einen AMQP-Plugin.

Lobster_data kann auf einen AMQP-Server zugreifen, der auf dem gleichen oder einem anderen Computer installiert wurde. Lobster_data ist dabei also in der Client-Rolle.

Hinweis: Dieser Eingangsagent kann auch verwendet werden, um von JMS-Server-Queues zu lesen.

images/download/attachments/36575286/AMQP-version-5-modificationdate-1578878042899-api-v2.png

(1) Nur relevant für das Zusatzmodul Load Balancing, um das Profil auf einem bestimmten Node zu starten.

(2) Auswahl eines AMQP- bzw. JMS-Aliases. Siehe Abschnitt AMQP-Verbindungen.

(3) Auswahl der Nachrichtenart (Subscriber, Topic, Routing oder RPC). Der Style RPC ist synchron, die anderen asynchron. Hinweis: Wenn Sie den Style RPC verwenden, dann ist es zusätzlich notwendig einen Antwortweg des Typs Eigene Klasse und der spezifischen Klasse PassBackDataResponse zu verwenden. Der Grund ist, dass bei einem RPC-Call eine Response erwartet wird vom aufrufenden Client und diese wird durch die erwähnte Antwortweg-Klasse in Lobster_data erzeugt und von dort an den Eingangsagenten und dann an den Client zurückgegeben. Siehe dazu allgemein auch Abschnitte Dritte Möglichkeit - Eigene Klasse im Antwortweg und AMQP-Netze mit Style RPC. Hinweis: Wenn Sie bei den Style Topic verwenden, dann erscheint auch die Checkbox Persistent ('Durable'). Setzen Sie diese Checkbox, falls es sich bei der in (4) angegebenen Queue um eine "durable" Queue handelt (eine solche Queue überlebt einen Neustart des Brokers). Bei ActiveMQ muss dabei die JMS Client ID in der Verbindung gesetzt sein. Wird das nicht getan, erzeugt das einen Fehler, den Sie direkt nicht erkennen können, sondern nur in den Server-Logs unter _data/error.logs in folgender Form:

...javax.jms.JMSException: You cannot create a durable subscriber without specifying a unique clientID on a Connection...

(4) Name der Queue, auf die gehört wird, bzw. das Topic. Siehe (3). Hinweis: Wenn ein Azure Service Bus verwendet wird und bei (3) Topic ausgewählt wurde, muss hier folgende Syntax verwendet werden: <Topicname>/subscriptions/<Subscriptionname>, also z. B. mytopic/subscriptions/mysubscription.

(5) Wenn Sie die empfangenen Nachrichten filtern wollen, können Sie eine JMS-API-Nachrichtenauswahl verwenden, mit der sie hier als Nachrichtenkonsument die gewünschten Nachrichten angeben können. Siehe Oracle JMS Message Selectors und den Abschnitt weiter unten dazu.

(6) Hier können Sie das Consumer Delivery Acknowledgement einstellen, also wie Lobster_data auf dem Message-Bus den Empfang einer Nachricht bestätigt, siehe z. B. hier. Ist die Checkbox nicht gesetzt, dann gilt das Default-Verhalten, d. h. der Empfang wird nach dem Anlegen der Backup-Datei des Profil-Jobs bestätigt (außer bei Nachrichten-Art RPC). Ist die Checkbox gesetzt, dann wird eine empfangene Nachricht erst nach erfolgreichem Job-Durchlauf bestätigt. Damit ist keine Verarbeitung im Hintergrund möglich (Parallelverarbeitung und Queueing von Jobs). Ist in den Antwortwegen Antwortwege entkoppelt ausführen gesetzt, dann wird der Empfang einer Nachricht ab Phase 6 immer bestätigt. Hinweis: Wird eine Nachricht von Lobster_data nicht bestätigt, dann greift die Einstellung des JMS-/AMQP-Servers und die Nachricht wird gegebenenfalls erneut zugestellt oder abgelehnt und auf die Dead Letter Queue umgeleitet. Ist das der Fall, kann man in solch einer Konstellation also, ähnlich wie bei einer Datenbank, am Ende der Verarbeitung im Profil eine "Transaktion committen", wenn kein Fehler aufgetreten ist. Im Falle eines Fehlers können dann z. B. Profile für die Fehlerbehandlung eingerichtet werden, die dann unter Umständen die fehlerhaften Nachrichten aus der Dead Letter Queue abarbeiten. Hinweis: Eine Dead Letter Queue kann auch über einen Antwortweg AMQP angelegt werden, wenn das Profil, das diesen Antwortweg benutzt, eine System-Variable AMQP_SYS_<Name des Queue-Arguments> definiert hat. Für RabbitMQ wäre das z. B. AMQP_SYS_x-dead-letter-exchange, siehe hier.

Hinweis

Eine AMQP-Message besteht aus Header und Body. Der Body enthält die Daten, die im Profil verarbeitet werden sollen. Zusätzlich kann der Header noch Parameter enthalten, die jeweils einen Namen und einen Wert haben. Beispielsweise wird der Header-Parameter NameX im Profil über eine im Profil definierte Variable MSG_CALL_NAMEX verfügbar. Der Variablenname muss also dem Parameter-Namen in Großbuchstaben mit vorangestelltem MSG_CALL_ entsprechen. Spezifische Beispiele: MSG_CALL_GROUPID, MSG_CALL_SUBJECT, MSG_CALL_MESSAGEID, MSG_CALL_CORRELATIONID.

JMS-Message-Selektoren

JMS-Message-Selektoren verwenden eine relativ komplexe Sprache, die so ähnlich aufgebaut ist wie eine SQL-WHERE-Klausel. Ein solcher Selektor kann zur Filterung auf Message Headers und Properties angewendet werden, aber nicht auf den Nachrichteninhalt. Folgend ein paar Beispiele, da die Oracle-Dokumentation an der Stelle etwas mager ist.

Element	Beschreibung	Beispiel-Selektor
Header fields	Alle Header außer JMSDestination, JMSExpiration und JMSReplyTo.	JMSPriority = 9
Properties	Message-Properties (es gelten die selben Regeln wie bei Java-Bezeichnern).	releaseYear = 1982
String	Strings in einfachen Anführungszeichen. Doppelte einfachen Anführungszeichen zum Escapen.	title = 'Sam''s'
Zahl	Zahlen in Java-Syntax (int und double).	releaseYear = 1982
Boolean	TRUE und FALSE.	isAvailable = TRUE
( )	Klammern.	(releaseYear < 1980) OR (releaseYear > 1989)
AND, OR, NOT	Logische Operatoren.	(releaseYear < 1980) AND NOT (title = 'Thriller')
=, <>, <, <=, >, >=	Vergleichsoperatoren.	(releaseYear < 1980) AND (title <> 'Thriller')
LIKE	String-Vergleich mit Wildcards '_' (steht für ein einziges Zeichen) und '%' (steht für 0 bis beliebig viele Zeichen).	title LIKE 'Thrill%'
IN	Wert in einer Menge von Strings finden. Der IN-Operator funktioniert nur für Mengen von Strings und nicht für Mengen von Zahlen.	title IN ('Off the wall', 'Thriller', 'Bad')
BETWEEN	Überprüft, ob eine Zahl in einem bestimmten Bereich liegt (beide Zahlen inklusive).	releaseYear BETWEEN 1980 AND 1989
IS NULL, IS NOT NULL	Überprüft, ob ein Wert NULL ist oder nicht.	releaseYear IS NOT NULL
*, +, -, /	Arithmetische Operatoren.	releaseYear 2 > 2000 - 20*

Hinweis: Sehen Sie sich im Antwortweg AMQP die Hinweise an, wie man Nachrichten "an Selektoren schicken" kann, d. h. wie man Nachrichten schicken kann, die von einem bestimmten Selektor abgegriffen werden können.

Profil-Suspendierung

Wenn Profile mit diesem Eingangsagenten suspendiert werden, dann werden während der Suspendierung keine Nachrichten angenommen, sondern verbleiben auf dem Broker. Wird die Suspendierung aufgehoben, kann es bis zu 60 Sekunden dauern, bis diese Nachrichten verarbeitet werden.