MessageSpecifier Interface (SAP Library - Enabling Application-to-Application Processes)

MessageSpecifier Interface

Use

Assume that you want to append an attachment to your message. The proxy runtime must take this into account when constructing the message. The proxy runtime provides an interface MessageSpecifier to be able to use special services of the proxy runtime.

Integration

The MessageSpecifier interface is an attribute of your generated consumer or provider proxy; its full name is com.sap.aii.proxy.xiruntime.core.MessageSpecifier.

Access to Methods of MessageSpecifier

Sender Side

You cannot access this object directly at the sender, because access to the MessageSpecifier interface is encapsulated using the proxy bean. Instead, you must use the proxy bean methods to get an instance of the MessageSpecifier interface, use its methods (see below), and then return it to the proxy class. The following methods exist:

● MessageSpecifier $messageSpecifier()

Gets an instance of the MessageSpecifier interface and initializes all attributes.

● MessageSpecifier $messageSpecifierRead()

Reads the MessageSpecifier interface without initializing attributes that were set previously. For example, this is necessary when you want to use the getMessageIdLastSent() method after a proxy call.

Caution

You can only use this method if you deploy the consumer bean as a Stateful Session Bean. Only in this way can you ensure that the Java EE application on the consumer side always references the same bean instance during the method call to the bean. In the case of stateless beans, this can be a different instance from the bean pool for each method. You specify the bean type in the deployment descriptor (file ejb-jar.xml).

● void $messageSpecifier(MessageSpecifier ms)

Sends the MessageSpecifier instance back to the proxy class.

Receiver Side

The implementing class for the provider proxy interface is derived from the Java proxy runtime class AbstractProxy. Therefore, you can directly access an instance variable messageSpecifier in the implementation. In this case, the generated bean gets the instance before the implementing class is called and then transfers it back to the proxy class.

Features

Messaging-System (MS) for Java EE Application

Method	Meaning
public void setMessagingTimeoutInMSec (long timeout);	Determines the validity period of a message: ● If an asynchronous message cannot be sent to the Integration Server within the period of validity it is persisted for MS monitoring. ● If the messaging system does not receive a response message for a synchronous message within the period of validity then an error is returned to the application. If the response message is received thereafter, the messaging system also persists this message for MS monitoring.
public void setQueueId(String id)	This method enables you to assign a serialization context to multiple messages to guarantee the quality of service exactly once in order. The string id can be a maximum of 16 characters long and must be in upper case. All asynchronous messages with the same serialization context are received in the same order at the receiver as they were put in the outbound queue during the COMMIT WORK on the sender side.
public String getQueueId()	Returns the predefined serialization context.

Payload (see also: Calling the Payload)

Method	Meaning
public String getInputPayload()	Returns the payload of the input message (after the system has called a consumer proxy or during inbound processing).
public String getOutputPayload()	Returns the payload of the output message (after the system has called a consumer proxy).
public void setPayload( String payload )	This method enables you to set the payload yourself instead of generating the data that was transferred to the proxy. In this case, it is the application itself that is responsible for the correct format of the payload. The proxy runtime completes the message header and forwards the message with the transferred payload.

Setting the Receiver

Method	Meaning
public void addReceiverService( String service)	Adds a service to the set of all receiver services of the consumer proxy.
public void addReceiver( java.lang.String partyName, java.lang.String partyAgency, java.lang.String partyScheme, java.lang.String service)	Adds a receiver to the set of all receivers of the consumer proxy. You must specify the communication party, issuing agency and identification scheme in cross-company communication.
public boolean removeReceiverService(String service)	Deletes a specific service from the set of all receiver services of the provider proxy.
public void clearReceivers()	Deletes all specified receivers.

Attachments

Method	Meaning
public MessageAttachment createAttachment( String name, String type, Object data)	Creates a new attachment object. For type you must specify the MIME type (for example, ‘text/html’).
public MessageAttachment addAttachment( String name, String type, Object data)	Generates a new attachment object, adds this to the set of attachments, and returns the attachment object.
public void addAttachment( MessageAttachment attachment)	Adds a new attachment to the set of attachments.
public boolean removeAttachment(MessageAttachment attachment);	Deletes the specified attachment.
public void clearAttachments();	Deletes all attachments. You must call this method on the receiver side so that the system does not return received attachments.
public MessageAttachment getAttachment(String name);	Returns the attachment with the name name.
public java.util.Enumeration getAttachments();	Returns a list of all attachments.

Determining the Sender at the Receiver

Method	Meaning
public String getSenderService()	Determines the service of a message received at the receiver.
public String getSenderPartyName()	Determines the name of a communication party of a message received at the receiver.
public String getSenderPartyAgency()	Determines the issuing agency of a message received at the receiver.
public String getSenderPartyScheme()	Determines the identification schema of a message received at the receiver.

Querying a Message ID

Method	Meaning
public com.sap.guid.IGUID getMessageID()	Queries the message ID when a message arrives. The method toString() provides the string representation of the ID.
public com.sap.guid.IGUID getMessageIDLastSent()	Queries the message ID when a message has been sent. The method toString() provides the string representation of the ID.
public com.sap.guid.IGUID getRefToMessageID	Queries the ID of a message, which is referenced by this message. For example, a response message uses this field to note which request message it belongs to.

Requesting Acknowledgments

Method	Requested Acknowledgment and Its Meaning
public void setSystemAckRequested( String ackListenerName)	Positive system acknowledgment. The receiver was reached successfully. For provider proxies, this means that the implementing class for the provider proxy was found and that the method for inbound processing could be called.
public void setSystemErrorAckRequested( String ackListenerName)	Negative system acknowledgment. Messaging 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 provider 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 during message processing at the receiver.

Note

The time at which a message has been successfully processed by a receiver depends on the receiver. The following is the case for a provider proxy: if the method executed at the receiver does not raise an exception, you can explicitly send an acknowledgment in the send step of an integration process (see the Sending an Acknowledgment section in Send Step).