Acknowledgments 

Verwendung

Mit Acknowledgments können Sie sich den Empfang von asynchronen Messages bestätigen lassen. Sie müssen Acknowledgments explizit im Anwendungsprogramm anfordern und können spezifizieren, welche Art der Rückmeldung sie erhalten möchten:

·        Positive oder negative Acknowledgments

·        System-Acknowledgments, über die die Laufzeitumgebung bestätigt, dass eine asynchrone Message den Empfänger erreicht hat.

·        Anwendungs-Acknowledgments, mit denen die erfolgreiche Verarbeitung der asynchronen Message beim Empfänger bestätigt wird.

Im Anwendungsprogramm können Sie den Status eines angeforderten Acknowledgments abfragen und auswerten.

Voraussetzungen

Folgende Empfänger unterstützen Acknowledgments:

·        ABAP und Java-Proxies (letztere zu XI 3.0 SP1)

·        Integrationsprozesse

·        IDocs, wobei diese nur dann Acknowledgments zurückgeben, wenn diese über das ALE audit konfiguriert wurden

·        Empfänger-Adapter unterstützen System-Acknowledgments, aber keine Anwendungs-Acknowledgments.

Funktionsumfang

Acknowledgment-Typen

Um Acknowledgments anzufordern, müssen Sie entsprechende Felder der Struktur PRX_ACK_REQUEST_DETAILS auf ‚X’ setzen. Die Felder haben folgende Bedeutung:

Details für Acknowledgement-Anforderung (Struktur PRX_ACK_REQUEST_DETAILS)

Feld	Angefordertes Acknowledgment
SYSTEM_OK	Positives System-Acknowledgment Der Empfänger wurde erfolgreich erreicht; für Server-Proxies bedeutet dies, dass die implementierende Klasse zum Server-Proxy gefunden wurde und die Methode zur Inbound-Verarbeitung aufgerufen werden konnte.
SYSTEM_ERROR	Negatives System-Acknowledgment Die Laufzeit der Exchange Infrastructure meldet einen Fehler während der Übertragung beziehungsweise der Verarbeitung der Message auf dem Weg zum Empfänger. Beispielsweise kann ein Fehler in einem Mapping-Programm oder ein nicht im Empfängersystem vorhandenes Server-Proxy dieses Acknowledgment auslösen.
APPLICATION_OK	Positives Anwendungs-Acknowledgment Die Message wurde vom Empfänger erfolgreich verarbeitet.
APPLICATION_ERROR	Negatives Anwendungs-Acknowledgment Während der Verarbeitung der Message beim Empfänger ist ein Fehler aufgetreten.

Wann eine Message von einem Empfänger erfolgreich verarbeitet worden ist, hängt vom Empfänger ab: Bei einem Server-Proxy ist dies der Fall, wenn die beim Empfänger ausgeführte Methode keine Ausnahme ausgelöst hat, bei einem Integrationsprozess können Sie im Sendeschritt explizit ein Acknowledgment versenden (siehe Abschnitt Acknowledgment senden unter Sendeschritt).

Sie können diese Felder einzeln setzen. Die ABAP-Proxy-Laufzeit bietet außerdem Konstanten an, mit denen Sie einige sinnvolle Feld-Kombinationen über eine einzige Zuweisung setzen können. Die folgende Tabelle zeigt, welche Felder mit Hilfe der Konstanten gesetzt werden können:

Acknowledgment-Konstanten des Interface IF_WSPROTOCOL_ASYNC_MESSAGING

Gesetztes Feld	Aknowledgement-Typ (Konstante)
	Transport (CO_TRANSPORT_ACKNOWLEDGMENT)	Application (CO_APPLICATION_ACKNOWLEDGMENT)	Complete (CO_COMPLETE_ACKNOWLEDGMENT)
SYSTEM_OK	X		X
SYSTEM_ERROR	X	X	X
APPLICATION_OK		X	X
APPLICATION_ERROR		X	X

Abfragen und Auswerten von Acknowledgments

Acknowledgment-Methoden des Interface IF_WSPROTOCOL_ASYNC_MESSAGING

Methode	Verwendung
SET_ACKNOWLEDGMENT_REQUESTED	Anforderung eines Acknowledgments auf Sender-Seite. Sie können über Konstanten des Interface oder über einzelne Felder die gewünschten Acknowledgments festlegen.
GET_ACKNOWLEDGMENT_REQUESTED	Auslesen, welche Acknowledgments angefordert wurden.
GET_ACKNOWLEDGMENT	Zeitnahes Abfragen des Acknowledgment-Status über die Instanz des Client-Proxy. Die Methode gibt ein Objekt vom Typ REF TO IF_WS_ACKNOWLEDGMENT zurück.

Abfragen des Acknowledgment-Objekts

Sie fragen im Anwendungsprogramm aktiv den Status des Acknowledgments ab, indem Sie ein Acknowledgment-Objekt abfragen. Sie haben folgende Möglichkeiten:

·        Wenn Sie noch auf die Instanz des Client-Proxy Zugriff haben, können Sie sich ein Acknowledgment-Objekt über die Methode GET_ACKNOWLEDGMENT zeitnah abfragen.

·        Wahrscheinlicher ist es, dass Sie zum Zeitpunkt, zu dem Sie den Status des Acknowledgments abfragen wollen, auf die Instanz des Client-Proxy keinen Zugriff mehr haben. In diesem Fall gehen Sie folgendermaßen vor (siehe auch das Beispiel unten):

...

                            a.      Holen Sie sich nach dem Proxy-Aufruf die Message-ID der versendeten Message (siehe: Auf die Message-ID zugreifen).

                            b.      Mit Hilfe der Message-ID können Sie sich das Acknowledgment-Objekt mit Hilfe der Methode CL_PROXY_ACCESS=>GET_ACKNOWLEDGMENT( [Message-ID] ) holen und auswerten.

Mit dem Acknowledgment-Objekt können Sie abfragen, ob und welche Acknowledgments empfangen wurden.

Auswertung des Acknowledgment-Objekts

Aus folgenden Gründen kann es mehrere Acknowledgments für eine Message geben:

·        Wenn Sie zu einer Message mehrere Acknowledgments angefordert haben. Haben Sie beispielsweise alle Acknowledgments angefordert und die Verarbeitung sowie die Übermittlung der Message war erfolgreich, wird ein positives System-Acknowledgment (SYSTEM_OK) vor dem positiven Anwendungs-Acknowledgment (APPLICATION_OK) versendet.

·        Hat die Message des Senders mehrere Empfänger im logischen Routing, kopiert der Integration Server die eingegangene Message und schickt jeweils eine Kopie an den jeweiligen Empfänger (Message-Verzweigung). Wenn der Empfänger Acknowledgments für die bei Integration Server eingegangene Message angefordert hat, überträgt sich diese Anforderung für jede neu entstandene Message. Auch diese neu entstandenen Messages können wieder mehrere Acknowledgments auslösen, wenn mehrere Acknowledgments für die ursprüngliche Message angefordert wurden.

Um die Abfrage von Acknowledgments zu vereinfachen, werden sie pro Empfänger aggregiert; sie ‚überschreiben’ sich gegenseitig, falls ein empfangenes Acknowledgment ein anderes obsolet macht. Beispielsweise ist beim Empfang eines positiven Anwendungs-Acknowledgments klar, dass der Empfänger erreicht wurde, so dass ein vorher empfangenes positives System-Acknowledgment überschrieben wird. Die Methode GET_STATUS_DETAIL aggregiert keine Acknowledgments.

Die Acknowledgments werden auf der Datenbank gespeichert. Für die drei folgenden Methoden müssen Sie den Parameter READ_AGAIN setzen, um den aktuellen Status von der Datenbank zu lesen. Um einen abgefragten Status erneut zu lesen, lassen Sie diesen Parameter ungesetzt, um den Datenbankzugriff zu vermeiden.

Acknowledgment-Methoden des Interface Acknowledgment-Methoden des Interface IF_WS_ACKNOWLEDGMENT 

Methode	Verwendung
GET_STATUS	Abfragen des aggregierten Status für einen Empfänger. Gibt es noch kein Acknowledgment, löst die Methode die Ausnahme NO_ACK_ARRIVED aus. Gab es eine Message-Verzweigung, gibt die Methode die Konstante CO_STAT_ACK_SYS_BRANCH für das Feld ACK_STATUS zurück. In diesem Fall können Sie den Status über die Methode GET_STATUS_TREE oder GET_STATUS _DETAIL abfragen.
GET_STATUS_TREE	Abfragen des aggregierten Status für mehrere Empfänger. Gibt es nur einen Empfänger, entspricht eine Tabellenzeile dem Rückgabewert von GET_STATUS. Ist die Tabelle leer, ist noch kein Acknowledgment empfangen worden.
GET_STATUS_DETAIL	Detaillierter Baum mit nicht aggregierten Status-Informationen zu den angeforderten Acknowledgments.

Der Report SXI_DEMO_ACK_READ gibt ein Beispiel zur Auswertung von Acknowledgments.

Beispiel

Anfordern eines Acknowledgments

Method sendWithACK.

DATA:

* Reference variables for proxy and exception class
 lo_clientProxy     TYPE REF TO [generierte Proxy-Klasse],
 lo_sys_exception   TYPE REF TO cx_ai_system_fault,
 lo_async_messaging TYPE REF TO if_wsprotocol_async_messaging,
 lo_msg_id_protocol TYPE REF TO if_wsprotocol_message_id,
 l_msg_id           TYPE SXMSGUID,
 l_ack_request      TYPE PRX_ACK_REQUEST_DETAILS.

* Structures to set and get message content
 ls_request         TYPE [Output-Message-Typ],

TRY.

* create proxy client

  CREATE OBJECT lo_clientProxy.

* get protocol for asynchronous messaging

  lo_async_messaging ?=
   lo_clientProxy->get_protocol( if_wsprotocol=>async_messaging ).

* Ask for transport acknowledgment

  clear l_ack_request.
  l_ack_request =
    IF_WSPROTOCOL_ASYNC_MESSAGING=>CO_TRANSPORT_ACKNOWLEDGMENT.
  lo_async_messaging->set_acknowledgment_requested( l_ack_request ).

* do asynchronous client proxy call

  CALL METHOD lo_clientProxy->execute_asynchronous
     EXPORTING output  = ls_request.

* get message id of sent message

  lo_msg_id_protocol ?=
    lo_clientProxy->get_protocol( if_wsprotocol=>message_id ).
  l_msg_id = lo_msg_id_protocol->get_message_id( ).

* send message

  COMMIT WORK.

  CATCH cx_ai_system_fault INTO lo_sys_exception.

*   Error handling

ENDTRY.

* Somehow pass the message ID to the caller for an evaluation
* at a later point in time

Return lo_msg_id.

Endmethod.

Abfragen eines Acknowledgments

Mit Hilfe der Message-ID können Sie später das Acknowledgment-Objekt abfragen:

Data:

lo_ack                   TYPE REF TO if_ws_acknowledgment,
l_ack_status_simple type PRX_ACK_STATUS,
l_ack_status_detail type PRX_ACK_STATUS_DETAIL_TABLE.

* read ack
lo_ack = cl_proxy_access=>get_acknowledgment( l_msg_id ).
l_ack_status_simple = lo_ack->get_status( ).
l_ack_status_detail = lo_ack->get_status_detail( ).