The body of an XMS message

The body of a message contains application data. However, a message can have no body, and comprise only the header fields and properties.

XMS supports five types of message body:

Bytes

The body contains a stream of bytes. A message with this type of body is called a bytes message. The IBytesMessage interface contains the methods to process the body of a bytes message.

Map

The body contains a set of name-value pairs, where each value has an associated data type. A message with this type of body is called a map message. The IMapMessage interface contains the methods to process the body of a map message.

Object

The body contains a serialized Java or .NET object. A message with this type of body is called an object message. The IObjectMessage interface contains the methods to process the body of an object message.

Stream

The body contains a stream of values, where each value has an associated data type. A message with this type of body is called a stream message. The IStreamMessage interface contains the methods to process the body of a stream message.

Text

The body contains a string. A message with this type of body is called a text message. The ITextMessage interface contains the methods to process the body of a text message.

The IMessage interface is the parent of all message objects and can be used in messaging functions to represent any of the XMS message types.

For information about the size and maximum and minimum values of each of these data types, see Table 1.

Bytes messages

The body of a bytes message contains a stream of bytes. The body contains only the actual data, and it is the responsibility of the sending and receiving applications to interpret this data.

Bytes messages are useful if an XMS application needs to exchange messages with applications that are not using the XMS or JMS application programming interface.

After an application creates a bytes message, the body of the message is write-only. The application assembles the application data into the body by calling the appropriate write methods of the IBytesMessage interface for .NET. Each time the application writes a value to the bytes message stream, the value is assembled immediately after the previous value written by the application. XMS maintains an internal cursor to remember the position of the last byte that was assembled.

When the application sends the message, the body of the message becomes read-only. In this mode, the application can send the message repeatedly.

When an application receives a bytes message, the body of the message is read-only. The application can use the appropriate read methods of the IBytesMessage interface to read the contents of the bytes message stream. The application reads the bytes in sequence, and XMS maintains an internal cursor to remember the position of the last byte that was read.

If an application calls the Reset method of the IBytesMessage interface when the body of a bytes message is writeable, the body becomes read-only. The method also repositions the cursor at the beginning of the bytes message stream.

If an application calls the Clear Body method of the IMessage interface for .NET when the body of a bytes message is read-only, the body becomes writeable. The method also clears the body.

Map messages

The body of a map message contains a set of name-value pairs, where each value has an associated data type.

In each name-value pair, the name is a string that identifies the value, and the value is an element of application data that has one of the XMS data types listed in Table 1. The order of the name-value pairs is not defined. The MapMessage class contains the methods to set and get name-value pairs.

An application can access a name-value pair randomly by specifying its name.

A .NET application can use the MapNames property to get an enumeration of the names in the body of the map message.

When an application gets the value of a name-value pair, the value can be converted by XMS into another data type. For example, to get an integer from the body of a map message, an application can call the GetString method of the MapMessage class, which returns the integer as a string. The supported conversions are the same as those that are supported when XMS converts a property value from one data type to another. For more information about the supported conversions, see Implicit conversion of a property value from one data type to another.

After an application creates a map message, the body of the message is readable and writable. The body remains readable and writable after the application sends the message. When an application receives a map message, the body of the message is read-only. If an application calls the Clear Body method of the Message class when the body of a map message is read-only, the body becomes readable and writable. The method also clears the body.

Object messages

The body of an object message contains a serializedJava or .NET object.

An XMS application can receive an object message, change its header fields and properties, and then send it to another destination. An application can also copy the body of an object message and use it to form another object message. XMS treats the body of an object message as an array of bytes.

After an application creates an object message, the body of the message is readable and writable. The body remains readable and writable after the application sends the message. When an application receives an object message, the body of the message is read-only. If an application calls the Clear Body method of the IMessage interface for .NET when the body of an object message is read-only, the body becomes readable and writable. The method also clears the body.

Stream messages

The body of a stream message contains a stream of values, where each value has an associated data type.

The data type of a value is one of the XMS data types listed in Table 1.

After an application creates a stream message, the body of the message is writable. The application assembles the application data into the body by calling the appropriate write methods of the IStreamMessage interface for .NET. Each time the application writes a value to the message stream, the value, and its data type are assembled immediately after the previous value written by the application. XMS maintains an internal cursor to remember the position of the last value that was assembled.

When the application sends the message, the body of the message becomes read-only. In this mode, the application can send the message multiple times.

When an application receives a stream message, the body of the message is read-only. The application can use the appropriate read methods of the IStreamMessage interface for .NET to read the contents of the message stream. The application reads the values in sequence, and XMS maintains an internal cursor to remember the position of the last value that was read.

When an application reads a value from the message stream, the value can be converted by XMS into another data type. For example, to read an integer from the message stream, an application can call the ReadString method, which returns the integer as a string. The supported conversions are the same as those that are supported when XMS converts a property value from one data type to another. For more information about the supported conversions, see Implicit conversion of a property value from one data type to another.

If an error occurs while an application is attempting to read a value from the message stream, the cursor is not advanced. The application can recover from the error by attempting to read the value as another data type.

If an application calls the Reset method of the IStreamMessage interface for XMS when the body of a stream message is write-only, the body becomes read-only. The method also repositions the cursor at the beginning of the message stream.

If an application calls the Clear Body method of the IMessage interface for XMS when the body of a stream message is read-only, the body becomes write-only. The method also clears the body.

Text messages

The body of a text message contains a string.

After an application creates an text message, the body of the message is readable and writable. The body remains readable and writable after the application sends the message. When an application receives an text message, the body of the message is read-only. If an application calls the Clear Body method of the IMessage interface for .NET when the body of an text message is read-only, the body becomes readable and writable. The method also clears the body.

• Data types for elements of application data
  To ensure that an XMS application can exchange messages with a IBM MQ classes for JMS application, both the applications must be able to interpret the application data in the body of a message in the same way.

Parent topic: XMS messages