Bestandteile der XI-Message

XI-Messages werden für die Empfängerrichtung vom Messaging-Service des Adapter-Framework erzeugt und aus Senderrichtung vom JCA-Resource-Adapter oder einem seiner Module. Sie sind die Java-Repräsentation der SOAP-XI-Messages, die zwischen dem Integration Server und dem Adapter-Framework transportiert werden.

Das Message -Interface erlaubt Ihnen den Zugriff auf alle öffentlichen Teile der XI-Message. Im Folgenden sind die Unterschiede der Klassen-Properties beschrieben.

Message-Identifizierung mit der Message-ID

Jede XI-Message muss in der gesamten Systemlandschaft eindeutig identifizierbar sein. Dies wird durch eine GUID (Globally Unique Identifier) nach ISO-11578 Standard erreicht. Jede XI-Message hat eine Message-ID unabhängig von ihrem Typ (asynchroner/synchroner Request, synchrone Response). Sie wird von ihrem jeweiligen Sender generiert. Der Standard stellt sicher, dass es äußerst unwahrscheinlich ist, dass dieselbe Message-ID zweimal generiert wird.

Das Message-Objekt enthält eine Richtungsinformation ( MessageDirection ), die von den Modulen verwendet werden kann. Die Richtungsinformation bildet zusammen mit der Message-ID den so genannten MessageKey . Der MessageKey wird in der MessageException und für das Audit-Protokoll verwendet.

Weitere Informationen: Erzeugung von Audit-Protokolleinträgen

RefToMessageID

RefToMessageID ist die Message-ID einer früheren Message, auf die sich die jetzige Message bezieht. Im Falle einer synchronen Response muss RefToMessageID auf die Message-ID der referenzierten Message gesetzt werden. Sonst muss RefToMessageID leer sein.

SequenceId und SerializationContext

Für einige Integrationsszenarien ist die Reihenfolge der Messages wichtig. Die Message hat die DeliverySemantic mit der Ausprägung Exactly Once In Order.

Messages eines Serialisierungskontextes müssen in der Reihenfolge weiterverschickt werden, in der sie empfangen werden. Der Serialisierungskontext des Adapter-Framework besteht aus Direction + QueueId + ToParty + ToService. QueueId entspricht der qRFC QueueId im Integration Server. Die QueueId kann über set/getSequenceId() gesetzt und gelesen werden.

Mit getSerializationContext() können Sie den Serialisierungskontext auslesen.

CorrelationID

Es kann notwendig sein, Messages miteinander zu korrelieren. Dazu enthält der XI-Message-Header das Feld ConversationID . Um das Feld zu setzen, werden die folgenden API-Methoden zur Verfügung gestellt:

• Message.getCorrelationId()
• Message.setCorrelationId()

Zusammenhang zwischen APIs und Message-Header-Felder

TimeSent und TimeReceived Zeitstempel

Die TimeSent-Property enthält den Zeitpunkt, zu dem die Message vom Adapter-Framework Messaging-Service geschickt wird. Ist die Message noch nicht gesendet, ist der Wert aus getTimeSent() undefiniert.

Die TimeReceived-Property enthält den Zeitpunkt, zu dem das Adapter-Framework die Message empfängt.

From/To-Adressierungselemente

Die Sender- (from) oder Empfänger- (to) Properties stehen für den Sender, beziehungsweise Empfänger einer Message. Sie bestehen aus den Elementen Partner und Kommunikationskomponente. Innerhalb einer Domäne definiert die Kombination aus Partner und Kommunikationskomponente eindeutig einen Message-Sender oder Message-Empfänger. Für A2A-Fälle wird üblicherweise die Partnerinformation leer gelassen. Die Kommunikationskomponente wird dagegen immer ausgefüllt. Ein Message-Ersteller muss daher auf jeden Fall immer die Kommunikationskomponete und den Kommunikationskanal angeben. Der Partner wird nur in B2B-Fällen ausgefüllt.

Weitere Informationen: Partner , Kommunikationskomponente , Kommunikationskanal

Grundsätzlich kann die Kommunikationskomponente eines Senders/Empfängers frei gewählt werden. Im Integration Server kann sie folgende Ausprägungen besitzen:

• Eine Business-Kommunikationskomponente
• Einen Business-Prozess
• Eine frei gewählte Bezeichnung, die üblicherweise in B2B-Szenarien zwischen Geschäftspartnern verwendet wird.

In der Action-Klasse wird das Interface definiert, das zwischen dem Sender und Empfänger verwendet wird. . Der Begriff Action ist identisch mit dem Interface, wie es im Enterprise Services Repository definiert wird.

Quality-of-Service

Qualitiy-of-Service beschreibt Mechanismen, die den Message-Transport betreffen. Dazu gehören:

• die garantierte Zustellung von Messages innerhalb der Process Integration
• die Ermittlung von doppelten Messages
• die Auslieferung in der richtigen Reihenfolge (Serialisierung).

Das XIMessage -Interface unterstützt den Ansatz, dass Quality-of-Service innerhalb der XI-Message angegeben wird. Folgende Ausprägungen für Quality-of-Service stehen zur Verfügung:

• Best Effort: Die Message wird ohne Garantie der Zustellung, Überprüfung auf doppelte Messages oder Serialisierungsmechanismen an den Empfänger geschickt.
• Exactly Once: Die Message wird genau einmal an den Empfänger geschickt. Eine Serialisierung wird nicht vorgenommen. Alle Komponenten, die an der Message-Verarbeitung teilnehmen (auch Module und der JCA-Adapter), müssen die genau einmalige Auslieferung der Message durch korrektes transaktionales Verhalten garantieren.
• Exactly Once In Order: Dieser Modus ist eine Erweiterung des Modus Exactly Once. Zusätzlich zu den oben angegebenen Merkmalen wird eine Serialisierung auf der Senderseite vorgenommen. Alle Komponenten müssen garantieren, dass Messages genau einmal zugestellt werden und zwar genau in der Reihenfolge, in der sie verschickt werden. Die Serialisierung wird durch eine Queue erreicht, die im Serialisierungskontext identifiziert wird.

Jede Message muss einen Wert für Quality-of-Service in der DeliverySemantics-Property enthalten.

Es werden zwei Arten der Message-Verarbeitung zur Verfügung gestellt:

• Verschicken Sie eine Message synchron, müssen sie die Ausprägung Best Effort für Quality-of-Service wählen.
• Verschicken Sie eine Message asynchron, wählen Sie Exactly Once oder Exactly Once In Order.

Eine Anwendung kann nur im synchronen Fall auf Fehlersituationen reagieren, da sie eine synchrone Response erhält. Im Falle asynchroner Kommunikation erwartet der Sender keine Antwort.

Message-Klasse

XI-Messages können von unterschiedlichen Klassen (ApplicationMessage, SystemError, etc.) abstammen. Verwenden Sie die API-Methode Message.getMessageClass() , um die Message-Klasse zu ermitteln.

Adapterspezifische Message-Attribute

Adapter können zusätzliche Attribute unterstützen, die in XI-Message-Header-Feldern enthalten sind. Über den Attribut-Namensraum und den technischen Namen des Attributs kann im Routing, Mapping und lesend in der Business Process Engine auf diese Attribute zugegriffen werden.

Das Setzen und Lesen dieser Felder erfolgt durch folgende API-Methoden:

• Message.setMessageProperty()
• Message.getMessageProperty()

Gestalten Sie das Setzen der Attribute im Senderkanal und das Auslesen im Empfängerkanal konfigurierbar, indem Sie die von Ihrem Adapter unterstützten Attribute in den Adaptermetadaten definieren.

In den Adaptermetadaten muss außerdem das Element AdapterTypeMetaData/DynamicAttributes eingefügt werden. Die einzelnen Attribute werden als Referenzen angegeben.

<DynamicAttributes>

<AttributeReference>

<ReferenceName>meinAttribut</ReferenceName>

<AttributeReference>

<DynamicAttributes>

Beschreiben Sie meinAttribut über ein <Attribute> -Element wie es für statische Konfigurationsattribute. Adapterspezifische Message-Attribute müssen immer vom Typ String sein.

Informationen zur Auswahl und Verwendung adapterspezifischer Message-Attribute finden Sie unter: Adapterspezifische Attribute im Message-Header

Message-Payload

Die Message-Interfaces unterscheiden zwischen der Anwendungs-Payload, die Dokument genannt wird und in der Regel ein XML Business-Dokument ist und den Attachments der Anwendungs-Payload. Eine Message kann keines oder ein Dokument und kein, ein oder mehrere Attachments enthalten.

Das Dokument wird innerhalb des Durchlaufs durch den Integration Server bearbeitet (beispielsweise durch Mapping). Attachments werden unverändert an den Empfänger weitergeleitet.

Um ein Attachment mit der Payload auszutauschen, verwenden Sie das Modul PayloadSwapBean. Dann können Sie das Attachment bearbeiten.

Weitere Informationen: PayloadSwapBean

Das Message -Interface stellt mehrere Methoden zum Anlegen und Lesen der Payload zur Verfügung. Mit folgenden Klassen kann eine Payload-Instanz bearbeitet werden:

• Payload
• TextPayload
• XMLPayload

Payload

Die Payload -Klasse stellt Methoden zum Setzen, Ermitteln und Löschen von Attributen bereit. Das XI-Protokoll basiert auf SOAP mit Attachments. MIME-Attachments besitzen Attribute wie beispielsweise Content-Disposition oder Content-Type. Sie können die Attribute mit folgenden Anweisungen verwalten:

• getAttributeNames()
• clearAttributes()
• getAttribute(String attributeName)
• setAttribute(String name, String value)
• removeAttribute(String attributeName)

TextPayload, XMLPayload

Bei TextPayload und XMLPayload ist der Zeichensatz (das Encoding) der Daten wichtig und muss richtig gesetzt und gelesen werden. Das Encoding wird im XML-Dokument festgelegt. Die Festlegung hier und im XML-Dokument müssen übereinstimmen, daher werden XMLPayloads als binäre Payloads behandelt.

• TextPayload.getEncoding() liefert den Java-String Encoding-Namen von dem Zeichensatz, in dem die Textdaten im Objekt enthalten sind.
  Hinweis

  Die Namen sind im Internet unter iana.org/assignments/character-sets definiert. Nicht alle werden vom Java Runtime Environment unterstützt, bei mehreren möglichen Namen ist der preferred-MIME Name zu wählen.

  • In Empfängerrichtung muss ein Adapter mit TextPayload.getEncoding() zuerst den Zeichensatz auslesen und, wenn nötig, in den Zeichensatz des externen Systems oder Protokolls konvertieren.
  • In Senderrichtung sollten Sie eine Konfigurationsmöglichkeit zur Verfügung stellen, um nicht-UTF-Textdaten in UTF zu konvertieren. Der Adapter muss den Zeichensatz der Textdaten mit setContent() bekannt geben, wenn er nicht setText() und damit UTF-8 verwendet.
• XMLPayload erbt von TextPayload und besitzt auch die Methoden getEncoding() und setContent() . Sie sind für das Encoding des XML-Dokumentes nicht relevant. Stattdessen wird das Encoding des XML-Dokumentes, wie in XML 1.1 spezifiziert, im Encoding-Attribut des xml-Elements vom XML-Dokument bekannt gegeben, beispielsweise "<?xml version="1.0" encoding="UTF-8"?>".
  • In Empfängerrichtung muss der Adapter das Encoding-Attribut lesen und, wenn nötig, das XML-Dokument in den Zeichensatz des externen Systems oder Protokolls konvertieren. In diesem Fall muss auch das Encoding im XML-Dokument angepasst werden.
  • In Senderrichtung sollten Sie eine Konfigurationsmöglichkeit zur Verfügung stellen, nicht-UTF XML-Daten in UTF zu konvertieren. In jedem Fall muss der Adapter den Zeichensatz der XML-Daten im Encoding-Attribut bekannt geben.

    Es wird empfohlen, UTF XML-Dokumente ausschließlich an das Adapter-Framework zu schicken, um Konvertierungsprobleme zu vermeiden (beispielweise durch Module, die keine XML-Parser verwenden, sondern die Payload als String behandeln).