This topic describes the SIMessage interface; the public
interface to a service integration bus message for use by mediations
and other service integration bus components.
The
version of Service Data Objects (SDO) supported by mediations is Version 1.
The
public interface SIMessage extends java.lang.Cloneable and java.lang.Serializable.
The
SIMessage interface has many methods allowing you to work with message
properties, header contents, routing path, metadata, and others:
- The method getDataGraph returns the SDO data
graph. This contains the SIMessage payload content in a tree representation.
Using the data graph, you can work directly with individual fields
in the message payload. For more information about SDO data graphs,
see SDO data graphs.
- You can transcode a message payload by calling
the method getNewDataGraph(format). It returns
a copy of the payload in the new format. You can write the new datagraph
back to the message using setDataGraph(DataGraph, format).
For more information, see Transcoding between message formats.
- If you want to log a message as a simple
byte stream, you can retrieve the message payload as a byte array
using the method getDataGraphAsBytes. For more
information about converting from data graph to bytes, and back again,
see Transcoding a message payload into a byte array and Transcoding a byte array into a message payload.
- There are methods to get, set, delete and clear user properties
and message properties. You can also retrieve a list of user property
names. For more information about working with properties, see Working with the message properties.
- Forward and reverse routing paths define a sequential list of
intermediate bus destinations through which messages pass to reach
a target bus destination. You use a routing path to apply the mediations
configured on several destinations to the messages sent along the
path. The following methods allow you to get and set the contents
of the ForwardRoutingPath and ReverseRoutingPath for an SIMessage:
- getForwardRoutingPath()
- setForwardRoutingPath()
- getReverseRoutingPath()
- setReverseRoutingPath()
For more information about routing paths, see Destination routing paths. For information
about how to work with routing addresses, see Setting routing addresses in a message header.
- If your mediation changes the content of the message, there is
a risk that the message is no longer valid. If the data graph is not
valid, the message cannot be sent through the service integration
bus or stored in the message store. In this case, the message is not well
formed. A message is well formed when all the values of the message
properties may be serialized, and the data graph of the message conforms
to the format of the message. You can test your message using the
method isWellFormed. It returns true when
the message contains a well formed data graph. This test has implications
for performance. For more information, see Setting tuning properties for a mediation.
- You can work with the time for the message to live, measured in
milliseconds from the time when the message was originally sent:
- The methods getTimeToLive and setTimeToLive allow
you to get and set the value of the TimeToLive field in the message
header. A value of 0 indicates that the message will never expire.
- The methods getRemainingTimeToLive and setRemainingTimeToLive allow
you to get the remaining time in milliseconds before the message expires,
and set the remaining time in milliseconds before the message should
expire.
For more information about SIMessage, see the API documentation.