Bestandteile der XI-Message 

Verwendung

XI-Messages werden für die Empfängerrichtung vom Messaging-Service des Adapter-Framework erzeugt und aus Senderrichtung vom JCA-Resource-Adapter. 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 werden die Unterschiede der unterschiedlichen Klassen-Properties beschrieben.

Funktionsumfang

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.

Darüber hinaus enthält das Message-Objekt 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. Siehe unter: Erzeugung von Audit-Protokolleinträgen

ConversationID und RefToMessageID

Um komplexere Kommunikationsvorgänge als nur einfache Request/Response-Mechanismen zu unterstützen, wird dem Sender der optionale ConversationID-Tag für jede Message zur Verfügung gestellt. Alle Messages mit derselben ConversationID gehören konzeptionell zum selben Kommunikationsvorgang oder Integrationsprozess.

Falls DeliverySemantic (siehe unten unter Quality-of-Service) die Ausprägung Exactly Once In Order hat, ist die ConversationID mit der Queue-ID des Integration Server identisch. Dadurch wird der Serialisierungskontext definiert und alle Messages mit derselben ConversationID und mit Quality-of-Service Exactly Once In Order müssen in der Reihenfolge ausgeliefert werden, in der sie empfangen wurden.

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.

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

XI-Message.Header-Feld	Wird gesetzt/gelesen durch API
ConversionID	Message.getCorrelationId() Message.setCorrelationId()
QueueID	Message.getConversationId() Message.setConversationId()
RefToMessageID	Message.getRefToMessageId() Message.setRefToMessageId()

TimeSent und TimeReceived Zeitstempel

Die TimeSent-Property enthält den Zeitpunkt, zu dem die Message vom Adapter-Framework Messaging-Service geschickt worden ist. Die TimeReceived-Property enthält den Zeitpunkt, zu dem das Adapter-Framework die Message empfangen hat.

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 Service. Innerhalb einer Domäne definiert die Kombination aus Partner und Service eindeutig einen Message-Sender oder Message-Empfänger. Für A2A-Fälle wird üblicherweise die Partnerinformation leer gelassen. Der Service wird dagegen immer ausgefüllt. Ein Message-Ersteller muss daher auf jeden Fall immer den Service und den Kommunikationskanal angeben. Der Partner wird nur in den entsprechenden (B2B)-Fällen ausgefüllt.

Die Partner-Agentur und das Schema, die im NormalizationManager verwendet werden, sind immer auf http://sap.com/xi/XI und XIParty zu setzen und können daher nicht in der Party-Klasse spezifiziert werden.

Grundsätzlich kann die Service-Property eines Senders/Empfängers frei gewählt werden. Im Integration Server kann ein Service folgende Ausprägungen besitzen:

·        Ein Business-System

·        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.

Quality-of-Service

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

·        die garantierte Zustellung von Messages innerhalb der SAP Exchange Infrastrucutre

·        die Ermittlung von doppelten Messages

·        die Auslieferung in der richtigen Reihenfolge (Serialisierung).

Algorithmen, die Qualitiy-of-Service garantieren, können auf unterschiedliche Weise bereitgestellt werden. Sie können auf End-to-End-Acknowledgments oder auf so genannten Quality-of-Service-Mustern basieren, wie z.B. Best Effort oder Exactly Once.

Das XIMessage-Interface unterstützt letzteren Ansatz. Quality-of-Service wird innerhalb der XI-Message angegeben. 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 (definiert durch die ConversationId) erreicht, die im Serialisierungskontext verwendet 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:

·        Falls Sie eine Message synchron verschicken wollen, dann müssen sie die Ausprägung Best Effort für Quality-of-Service wählen.

·        Falls Sie eine Message asynchron verschicken wollen, dann 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.

Bieten Sie hierzu die gleiche Möglichkeit an, wie z.B. SAP im File-/FTP-Adapter. Details finden Sie in den Adaptermetadaten des File-/FTP-Adapters im Integration Repository im Namensraum http://sap.com/xi/XI/System der Software-Komponente SAP BASIS.

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

<DynamicAttributes>

<AttributeReference>

   <ReferenceName>meinAttribut</ReferenceName>

<AttributeReference>

<DynamicAttributes>

Beschreiben Sie meinAttribut über ein <Attribute>-Element, wie es für statische Konfigurationsattribute auch der Fall ist. 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 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 (z.B. durch Mapping). Die Attachments werden unverändert an den Empfänger weitergeleitet.

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

Bei TextPayload und XMLPayload ist der Zeichensatz (das Encoding) der Daten wichtig und muss richtig gesetzt und gelesen werden:

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

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.

¡        Im Empfänger-/Outbound-Falle muss ein Adapter mit TextPayload.getEncoding() zuerst den Zeichensatz auslesen und, wenn nötig, in den Zeichensatz des externen Systems oder Protokolls konvertieren.

¡        Im Sender-/Inbound-Fall sollte es im Adapter konfigurierbar sein, nicht-UTF-8-Textdaten nach UTF-8 zu konvertieren. In jedem Falle muss der Adapter den Zeichensatz der Textdaten mit setContent() bekannt geben, wenn er nicht setText() und damit UTF-8 verwendet.

·        XMLPayload erbt von TextPayload und besitzt damit auch die Methode getEncoding() und setContent(). Diese sind jedoch 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, z.B. „<?xml version="1.0" encoding="UTF-8"?>“.

¡        Im Empfänger-/Outbound-Fall muss ein Adapter das Encoding-Attribut lesen und, wenn nötig, das XML-Dokument in den Zeichensatz des externen Systems oder Protokolls konvertieren.

¡        Im Sender-/Inbound-Fall sollte es im Adapter konfigurierbar sein, nicht-UTF-8 XML-Daten nach UTF-8 konvertieren. In jedem Fall muss der Adapter den Zeichensatz der XML-Daten im Encoding-Attribut bekannt geben.