Acknowledgments 

Use

Acknowledgments enable you to confirm that an asynchronous message has been received. You must explicitly request acknowledgments in the application program and can specify what kind of confirmation you want to receive.

·        Positive or negative acknowledgments.

·        System acknowledgments used by the runtime environment to confirm that an asynchronous message has reached the receiver.

·        Application acknowledgments used to confirm that the asynchronous message has been successfully processed at the receiver.

In the application program, you can query and evaluate the status of an acknowledgment.

Prerequisites

The following receivers support acknowledgments:

·        ABAP and Java proxies (XI 3.0 SP1 for the latter)

·        Integration processes

·        IDocs (note that IDocs only return acknowledgments when they have been configured using the ALE audit)

·        Receiver adapters support system acknowledgments but not application acknowledgments.

Features

Requesting Acknowledgments

To request one or more acknowledgments, use the following methods of the MessageSpecifier interface:

Methods for Acknowledgment Request

Field	Requested Acknowledgment
public void setSystemAckRequested (String ackListenerName);	Positive system acknowledgment. The receiver was reached successfully. For server proxies, this means that the implementing class for the server proxy was found and that the method for inbound processing could be called.
public void setSystemErrorAckRequested (String ackListenerName);	Negative system acknowledgment. SAP Exchange Infrastructure runtime reports that an error has occurred during transfer or processing of the message on its way to the receiver. For example, an error in a mapping program or a missing server proxy in the receiver system could trigger this acknowledgment.
public void setApplicationAckRequested (String ackListenerName);	Positive application acknowledgment. The message was processed by the receiver successfully.
public void setApplicationErrorAckRequested (String ackListenerName);	Negative application acknowledgment. An error occurred and an exception of type ApplicationFaultException was triggered during message processing at the receiver. The fault message for the exception is, in this case, part of the acknowledgement message.

The time at which a message has been successfully processed by a receiver depends on the receiver. For a server proxy, this happens when the method executed at the receiver has not triggered an exception; for an integration process, you can send an acknowledgment explicitly in the send step (see the Sending an Acknowledgment section in Send Step).

ackListenerName is the name of a bean that you deploy together with the application program at the sender to query the acknowledgment.

Receiver Bean

The name ackListenerName, which is transferred with the request methods, is the name of an EJB 2.0 receiver bean that is required to query the acknowledgement. The name follows the same conventions as proxy beans, for example:

sap.com/MyTest/MyTestAckBean or localejbs/MyTestAckBean.

The home interface, remote interface, localHome interface, and local interface of the receiver bean must be declared in the deployment descriptor as follows (file ejb-jar.xml) so that they can be found by the Java proxy runtime:

com.sap.aii.proxy.xiruntime.ack.AckListenerHome
com.sap.aii.proxy.xiruntime.ack.AckListenerRemote
com.sap.aii.proxy.xiruntime.ack.AckListenerLocalHome
com.sap.aii.proxy.xiruntime.ack.AckListenerLocal

The bean must implement the following Java interface of the Java proxy runtime:

com.sap.aii.proxy.xiruntime.ack.AckListener

The interface only has one method, which is called as soon as the Java proxy runtime receives an acknowledgment.

onAck(com.sap.aii.proxy.xiruntime.ack.AckMessage ack).

This method must be part of the local and localHome interfaces of the receiver bean and be implemented in the bean. If an acknowledgement is requested using one of the methods mentioned above, when the message is sent, the Java proxy runtime registers the name of the receiver bean along with the message ID in a table.

Querying and Evaluating Acknowledgments

When an acknowledgment message is received, the Java proxy runtime determines the receiver bean by using the message ID that the acknowledgment message references, instantiates the bean, and then calls the onAck() method. Using the AckMessage interface, the Java proxy runtime transfers the detailed information for the method by using the acknowledgment.

The Java proxy runtime does not aggregate acknowledgments. The onAck() method is called for every requested acknowledgement message.

Methods of the AckMessage Interface

Method	Return Value(s)
String getStatus();	Status of the acknowledgment ·        OK if a positive acknowledgment was received ·        Error if a negative acknowledgment was received ·        AckRequestNotSupported if the requested acknowledgment is not supported, or if the message for which the acknowledgment was requested was branched and sent to multiple receivers There are further methods for the last two values, which can be used to identify the exact cause of the error (see below).
String getCategory();	Error category transient or permanent. Only relevant if getStatus() has returned the value Error. If getCategory() has the value transient, the asynchronous message has not yet been transferred successfully (for example, if the receiver cannot be reached). However, it may be possible to transfer the message at a later time.
String getType();	One of the following acknowledgment types (see above): ApplicationAck, ApplicationError, SystemAck, or SystemError.
IGUID getRefToMsgId();	ID of the message for which you requested the acknowledgment.
String getRefToMsgIdAsString();	ID of the message as a string for which you requested the acknowledgment.

Troubleshooting

If getStatus() returned the value Error, you can use the following methods to get more information about the cause of the error:

AckMessage methods for getStatus() == “Error”

Method	Return Value
String getErrorCode();	Error code
String[] getErrorParameters();	Up to four error messages or null if no message is displayed.
String getApplicationFaultMessage();	Fault message. Only relevant for getStatus() = “Error” and getType() = “ApplicationError” (see also: Error Handling).
String getApplicationFaultMessageNamespace();	Namespace of the fault message. Only relevant for getStatus() = “Error” and getType() = “ApplicationError”.

If getStatus() has returned the value AckRequestNotSupported, you can use the following methods to find out which acknowledgment type is not supported by the receiver. Each of these methods returns true if one of the XI runtime components or the receiver does not support the requested acknowledgment:

AckMessage Methods for getStatus() == “AckRequestNotSupported”

boolean systemNotSupported();

boolean systemErrorAckNotSupported();

boolean applicationAckNotSupported();

boolean applicationErrorAckNotSupported();

Constants

The return values specified above can also be evaluated by using constants:

Constants of the Class “com.sap.aii.proxy.xiruntime.ack.AckConstant”

Constant	Value
static AckConstant CATEGORY_PERMANENT	“permanent”
static AckConstant CATEGORY_TRANSIENT	“transient”
static AckConstant STATUS_ERROR	“Error”
static AckConstant STATUS_NOT_SUPPORTED	“AckRequestNotSupported”
static AckConstant STATUS_OK	“OK”
static AckConstant TYPE_APPLICATION_ACK	“ApplicationAck”
static AckConstant TYPE_APPLICATION_ERROR	“ApplicationError”
static AckConstant TYPE_SYSTEM_ACK	“SystemAck”
static AckConstant TYPE_SYSTEM_ERROR	“SystemError”

The class also has the methods toString(), valueOf(), and inherited methods of the class java.lang.Object.