com.sap.engine.interfaces.messaging.api

Interface Message

All Superinterfaces:

Serializable

public interface Message
extends Serializable

A Message is what an application sends or receives when interacting with the Messaging System.
The Message interface is modeled to be as generic (i.e. protocol independent) as possible from the application's point of view. It contains only the most common information that is important to the sender and receiver of a message.

The Message interface was defined with the following goals in mind:

• Unified message interface that is capable of supporting multiple XML messaging protocols, e.g. XI, BC, MML, RNIF, CIDX, etc. (e.g. ebXML , BizTalk).
• A high level API that hides all the low level messaging details and offers a simple abstraction to business applications to send and receive business documents.
• The interface supports XML/text only payloads and XML payloads with binary attachments.
• The interface supports different versions of XML protocols.

Message is composed of header fields and payload. The header fields have accessor methods directly in the Message interface. This approach is used to be consistent with JMS specification.
Header fields include:

• Message ID (generated by the MessagingSystem and is read-only to applications)
• FromParty and ToParty (i.e. sender and recipient addresses)
• FromService and ToService (i.e. sending and receiving services)
• Action (identifies the process to be executed on the message)
• Description (optional descriptive text for the message)
• Sequence ID (the serialization context for EOIO processing)
• Correlation ID (indicates a series of messages that all belong to one correlation context)
• Time sent and received (i.e. timestamp)

Not all of the message header fields are expected to be supported by all Messages, due to the inherent differences in protocols. When the implementation of the Message interface for a particular protocol does not support a header field (e.g. a correlation ID), it can throw an InvalidParamException or ignore the parameter on set methods and return null on get methods.

Each Message must have one XML payload set as document. In addition to that, it might have any number of attachments of type XML, text or binary. The Message interface defines several methods for applications to deal with payloads:

• Factory methods to create an empty payload of a specific type.
• Add a payload to the message.
• Get a payload by name or interat over the payloads of a message.

Once a payload is added to the Message, it can not be removed again. To do that, a new Message has to be created and populated with the new payloads.

Method Summary

Modifier and Type	Method and Description
void	addAttachment(Payload attachment) Adds an attachment to the message.
int	countAttachments() Returns the number of attachments in this message.
ErrorInfo	createErrorInfo() Creates a new protocol implementation specific version of the ErrorInfo container interface and returns it.
Payload	createPayload() Creates an empty binary payload.
TextPayload	createTextPayload() Creates an empty text payload.
XMLPayload	createXMLPayload() Creates an empty XML payload.
Action	getAction() Returns the Action in the service that shall process this message.
Payload	getAttachment(String name) Returns an attachment by name if the XML message protocol used for this message supports attachment names.
Iterator	getAttachmentIterator() Returns an iterator to iterate over the attachments.
String	getCorrelationId() Returns the correlation ID that identifies a sequence messages, which semantically belong together.
DeliverySemantics	getDeliverySemantics() Returns the delivery semantics (QoS) of the message.
String	getDescription() Returns a descriptive text for the message.
XMLPayload	getDocument() Returns the main document as XMLPayload.
ErrorInfo	getErrorInfo() Returns the ErrorInfo container of the current message, if available.
Party	getFromParty() Returns the Party object that represents the sender.
Service	getFromService() Returns the Service object that represents the service that originally sent this message.
Payload	getMainPayload() Returns the main payload.
MessageClass	getMessageClass() Returns the message class of this message.
MessageDirection	getMessageDirection() Returns the direction of the message.
String	getMessageId() Returns the unique message ID.
MessageKey	getMessageKey() Returns the MessageKey.
String	getMessageProperty(MessagePropertyKey key) Returns the value of an additional message property, in case that such an value exists.
String	getMessageProperty(String namespace, String name) Deprecated. Use getMessageProperty(MessagePropertyKey), instead.
Set<MessagePropertyKey>	getMessagePropertyKeys() Returns all keys of existing additional message property, which can be used to retrieve the corresponding values.
String	getProtocol() Returns the protocol of this message (i.e. message format)
String	getRefToMessageId() Returns the ID of the message that this message refers to (or is in response to).
String	getSequenceId() Returns the ID that identifies the sequence of an EOIO message exchange.
String	getSerializationContext() This method returns the message protocol specific serialization context value, for this message.
long	getTimeReceived() Returns the time when the message was received.
long	getTimeSent() Returns the time when the message was sent.
Party	getToParty() Returns the Party object that represents the receiver.
Service	getToService() Returns the Service object that represents the service that will ultimately process this message.
boolean	isAck() Returns if the current message is an acknowledgement message.
boolean	isAck(AckType ackType) Returns if the current message is an acknowledgement message of the specified type.
boolean	isAckRequested() Returns if for the current message an acknowledgement message is requested.
boolean	isAckRequested(AckType ackType) Returns if for the current message an acknowledgement message of the specified type is requested.
void	removeAttachment(String name) Removes an attachment by name if the XML message protocol used for this message supports attachment names.
void	removeMessageProperty(MessagePropertyKey key) Removes the entry of an additional message property, in case that such an entry exists.
void	setCorrelationId(String id) Sets the correlation ID that identifies a sequence of message, which sematically belong together.
void	setDeliverySemantics(DeliverySemantics ds) Sets the delivery semantics (QoS) of the outgoing message.
void	setDescription(String description) Sets the description of the message
void	setDocument(XMLPayload document) Sets the main document.
void	setErrorInfo(ErrorInfo errorInfo) Sets the ErrorInfo container for the current message, that was created with createErrorInfo method before.
void	setMainPayload(Payload payload) Sets the main payload.
void	setMessageProperty(MessagePropertyKey key, String value) Sets an additional message field, if supported by the Message protocol implementation.
void	setMessageProperty(String namespace, String name, String value) Deprecated. Use setMessageProperty(MessagePropertyKey, String), instead.
void	setRefToMessageId(String id) Sets the ID that indicates which message this message refers to.
void	setSequenceId(String id) Sets the ID that identifies the sequence of an EOIO message exchange.

Method Detail

getSerializationContext

String getSerializationContext()

This method returns the message protocol specific serialization context value, for this message. The AbstractMessage implements the default serialization context as the Direction + SequenceId + ToParty.

Returns:

The message protocol specific serialization context value.

addAttachment

void addAttachment(Payload attachment)
            throws PayloadFormatException

Adds an attachment to the message.

Parameters:

attachment - the payload that will be added to the message as an attachment.

Throws:

PayloadFormatException - if the payload is invalid.

countAttachments

int countAttachments()

Returns the number of attachments in this message.

Returns:

the number of attachments.

createPayload

Payload createPayload()

Creates an empty binary payload.

Returns:

Payload.

createTextPayload

TextPayload createTextPayload()

Creates an empty text payload.

Returns:

TextPayload.

createXMLPayload

XMLPayload createXMLPayload()

Creates an empty XML payload.

Returns:

XMLPayload.

getAction

Action getAction()

Returns the Action in the service that shall process this message.

Returns:

the action to process the message.

getAttachment

Payload getAttachment(String name)

Returns an attachment by name if the XML message protocol used for this message supports attachment names.

Parameters:

name - the name of a particular attachment.

Returns:

attachment with the matching name or null.

removeAttachment

void removeAttachment(String name)

Removes an attachment by name if the XML message protocol used for this message supports attachment names.

Parameters:

name - the name of a particular attachment to be removed.

getAttachmentIterator

Iterator getAttachmentIterator()

Returns an iterator to iterate over the attachments. The objects returned by this iterator will implement the Payload interface.

Returns:

Iterator of the attachement payloads.

getSequenceId

String getSequenceId()

Returns the ID that identifies the sequence of an EOIO message exchange.

Returns:

the sequence id or null if this message is not part of a sequence.

getCorrelationId

String getCorrelationId()

Returns the correlation ID that identifies a sequence messages, which semantically belong together.

Returns:

the correlation id or null if this message is not part of a correlation.

getDeliverySemantics

DeliverySemantics getDeliverySemantics()

Returns the delivery semantics (QoS) of the message.

Returns:

DeliverySemantics

getDescription

String getDescription()

Returns a descriptive text for the message.

Returns:

a message description.

getDocument

XMLPayload getDocument()

Returns the main document as XMLPayload. If the main document was set with setMainPayload, this method will throw an RuntimeException (ClassCastException).

Returns:

the main document.

getMainPayload

Payload getMainPayload()

Returns the main payload.

Returns:

the main payload.

getFromParty

Party getFromParty()

Returns the Party object that represents the sender.

Returns:

the sender party.

getFromService

Service getFromService()

Returns the Service object that represents the service that originally sent this message.

Returns:

the sender service.

getMessageDirection

MessageDirection getMessageDirection()

Returns the direction of the message. The direction is with respect to the Messaging System, so a message that is created from the MessageFactory will have a direction of OUTBOUND and a method received by a MessageListener will have a direction of INBOUND.

Returns:

the direction of the message.

getMessageId

String getMessageId()

Returns the unique message ID. There is no corresponding setMessageId() method because the message ID is set by the MessagingSystem in order to guarantee that it is a) unique and b) in the format required by the underlying messaging protocol.

Returns:

a unique ID for this message.

getMessageKey

MessageKey getMessageKey()

Returns the MessageKey. The message key is slightly different from the message id. It not only has the message id itself, but also contains a parameter indicating the direction.

Returns:

the message key.

getProtocol

String getProtocol()

Returns the protocol of this message (i.e. message format)

Returns:

protocol of this message.

getRefToMessageId

String getRefToMessageId()

Returns the ID of the message that this message refers to (or is in response to).

Returns:

message ID of the message this message refers to or null if this message does not refer to a previous message.

getToParty

Party getToParty()

Returns the Party object that represents the receiver.

Returns:

the receiver party.

getToService

Service getToService()

Returns the Service object that represents the service that will ultimately process this message.

Returns:

the receiver service.

getTimeReceived

long getTimeReceived()

Returns the time when the message was received.

Returns:

a timestamp in milliseconds.

getTimeSent

long getTimeSent()

Returns the time when the message was sent. If the message isn't sent yet the return value is unspecified.

Returns:

a timestamp in milliseconds.

setDescription

void setDescription(String description)
             throws InvalidParamException

Sets the description of the message

Parameters:

description - text to describe the message

Throws:

InvalidParamException - if the description text is invalid.

setRefToMessageId

void setRefToMessageId(String id)
                throws InvalidParamException

Sets the ID that indicates which message this message refers to. When a new response message is created, this method needs to be invoked with the return value of a call the getMessageId on the request message.

Parameters:

id - the ID of the message that this message refers to.

Throws:

InvalidParamException - if the ID is invalid.

setSequenceId

void setSequenceId(String id)
            throws InvalidParamException

Sets the ID that identifies the sequence of an EOIO message exchange.

Parameters:

id - the sequence ID

Throws:

InvalidParamException - if the ID is invalid

setCorrelationId

void setCorrelationId(String id)
               throws InvalidParamException

Sets the correlation ID that identifies a sequence of message, which sematically belong together.

Parameters:

id - the correlation ID

Throws:

InvalidParamException - if the ID is invalid

setDeliverySemantics

void setDeliverySemantics(DeliverySemantics ds)
                   throws InvalidParamException

Sets the delivery semantics (QoS) of the outgoing message.

Parameters:

ds - is the delivery semantics (i.e. BestEffort, ExactlyOnce, or ExactlyOnceInOrder)

Throws:

InvalidParamException - is thrown when the value is invalid or not support by the protocol.

setDocument

void setDocument(XMLPayload document)
          throws PayloadFormatException

Sets the main document.

Parameters:

document - the document.

Throws:

PayloadFormatException - if the payload is invalid.

setMainPayload

void setMainPayload(Payload payload)
             throws PayloadFormatException

Sets the main payload. If the main payload was set with this method, it cannot be read with the getDocument method.

Parameters:

payload - the main payload.

Throws:

PayloadFormatException - if the payload is invalid.

getMessageClass

MessageClass getMessageClass()

Returns the message class of this message.

Returns:

the message class.

setMessageProperty

void setMessageProperty(String namespace,
                        String name,
                        String value)
                 throws InvalidParamException

Deprecated. Use setMessageProperty(MessagePropertyKey, String), instead.

Parameters:

value - string value

name - string name

namespace - string namespace

Throws:

InvalidParamException - InvalidParamException

getMessageProperty

String getMessageProperty(String namespace,
                          String name)

Deprecated. Use getMessageProperty(MessagePropertyKey), instead.

Parameters:

name - string name

namespace - string namespace

Returns:

The value for the given namespace/name combination, or null, when no such value exists.

setMessageProperty

void setMessageProperty(MessagePropertyKey key,
                        String value)
                 throws InvalidParamException

Sets an additional message field, if supported by the Message protocol implementation. Such additional fields will not be visible as an own table column in the MS message monitoring, since it is to be stored as part of the message header. This mechanism allows different protocol implementations to support more message fiels, as per default available in the MS Message interface. Such fields can be accessed through this API method, without casting to the specific Message implementation.

Parameters:

key - The key (consisting of name and namespace) of the property to set.

value - The value of the property to set. When null is given as the value param, an already set value will be deleted.

Throws:

InvalidParamException - If either the length of one of the parameters is too long, or in case of an unknown/not allowed namespace/name combination (but only if the Message implementation has the necessary knowledge about the valid namespace/name pairs).

getMessageProperty

String getMessageProperty(MessagePropertyKey key)

Returns the value of an additional message property, in case that such an value exists.

Parameters:

key - The key (consisting of name and namespace) of the property to set.

Returns:

The value for the given namespace/name combination, or null, when no such value exists.

removeMessageProperty

void removeMessageProperty(MessagePropertyKey key)

Removes the entry of an additional message property, in case that such an entry exists.

Parameters:

key - The key (consisting of name and namespace) of the property to be removed.

getMessagePropertyKeys

Set<MessagePropertyKey> getMessagePropertyKeys()

Returns all keys of existing additional message property, which can be used to retrieve the corresponding values.

Returns:

A set of all existing MessagePropertyKeys.

isAck

boolean isAck()

Returns if the current message is an acknowledgement message.

Returns:

True, if the current message is an acknowledgement message, otherwise false.

isAck

boolean isAck(AckType ackType)

Returns if the current message is an acknowledgement message of the specified type.

Parameters:

ackType - The acknowledgement type to be checked.

Returns:

True, if the current message is an acknowledgement message of the specified type, otherwise false.

isAckRequested

boolean isAckRequested()

Returns if for the current message an acknowledgement message is requested.

Returns:

True, if for the current message an acknowledgement message is requested, otherwise false.

isAckRequested

boolean isAckRequested(AckType ackType)

Returns if for the current message an acknowledgement message of the specified type is requested.

Parameters:

ackType - The acknowledgement type to be checked.

Returns:

True, if for the current message an acknowledgement message of the specified type is requested, otherwise false.

createErrorInfo

ErrorInfo createErrorInfo()

Creates a new protocol implementation specific version of the ErrorInfo container interface and returns it.

Returns:

The implementation of the ErrorInfo container interface.

setErrorInfo

void setErrorInfo(ErrorInfo errorInfo)
           throws InvalidParamException

Sets the ErrorInfo container for the current message, that was created with createErrorInfo method before.

Parameters:

errorInfo - The ErrorInfo container to be set for the current message.

Throws:

InvalidParamException - InvalidParamException

getErrorInfo

ErrorInfo getErrorInfo()

Returns the ErrorInfo container of the current message, if available.

Returns:

The ErrorInfo container of the current message, or null, if not available.