Sun Java System Message Queue 4.2 Developer's Guide for Java Clients

Composing Messages

The JMS Session interface provides methods for creating each type of message, as shown in Table 2–8. For instance, you can create a text message with a statement such as

TextMessage  outMsg = mySession.createTextMessage();

In general, these methods create a message with an empty body; the interfaces for specific message types then provide additional methods for filling the body with content, as described in the sections that follow.

Table 2–8 Session Methods for Message Creation

Name 

Description 

createMessage

Create null message 

createTextMessage

Create text message 

createStreamMessage

Create stream message 

createMapMessage

Create map message 

createObjectMessage

Create object message 

createBytesMessage

Create bytes message 


Note –

Some of the message-creation methods have an overloaded form that allows you to initialize the message body directly at creation: for example,

TextMessage
   outMsg = mySession.createTextMessage("Hello, World!");

These exceptions are pointed out in the relevant sections below.


Once a message has been delivered to a message consumer, its body is considered read-only; any attempt by the consumer to modify the message body will cause an exception (MessageNotWriteableException) to be thrown. The consumer can, however, empty the message body and place it in a writeable state by calling the message method clearBody:

outMsg.clearBody();

This places the message in the same state as if it had been newly created, ready to fill its body with new content.

Composing Text Messages

You create a text message with the session method createTextMessage. You can either initialize the message body directly at creation time

TextMessage  outMsg = mySession.createTextMessage("Hello, World!");

or simply create an empty message and then use its setText method (see Table 2–9 ) to set its content:

TextMessage  outMsg = mySession.createTextMessage();
outMsg.setText("Hello, World!");
Table 2–9 Text Message Composition Method

Name 

Description 

setText

Set content string 

Composing Stream Messages

The session method createStreamMessage returns a new, empty stream message. You can then use the methods shown in Table 2–10 to write primitive data values into the message body, similarly to writing to a data stream: for example,

StreamMessage  outMsg = mySession.createStreamMessage();
outMsg.writeString("The Meaning of Life");
outMsg.writeInt(42);
Table 2–10 Stream Message Composition Methods

Name 

Description 

writeInt

Write integer to message stream 

writeByte

Write byte value to message stream 

writeBytes

Write byte array to message stream 

writeShort

Write short integer to message stream 

writeLong

Write long integer to message stream 

writeFloat

Write floating-point value to message stream 

writeDouble

Write double-precision value to message stream 

writeBoolean

Write boolean value to message stream 

writeChar

Write character to message stream 

writeString

Write string to message stream 

writeObject

Write value of object to message stream 

reset

Reset message stream 

As a convenience for handling values whose types are not known until execution time, the writeObject method accepts a string or an objectified primitive value of class Integer, Byte, Short, Long, Float, Double , Boolean, or Character and writes the corresponding string or primitive value to the message stream: for example, the statements

Integer  meaningOfLife = new Integer(42);
outMsg.writeObject(meaningOfLife);

are equivalent to

outMsg.writeInt(42);

This method will throw an exception (MessageFormatException) if the argument given to it is not of class String or one of the objectified primitive classes.

Once you’ve written the entire message contents to the stream, the reset method

outMsg.reset();

puts the message body in read-only mode and repositions the stream to the beginning, ready to read (see Processing Messages). When the message is in this state, any attempt to write to the message stream will throw the exception MessageNotWriteableException. A call to the clearBody method (inherited from the superinterface Message) deletes the entire message body and makes it writeable again.

Composing Map Messages

Table 2–11 shows the methods available in the MapMessage interface for adding content to the body of a map message. Each of these methods takes two arguments, a name string and a primitive or string value of the appropriate type, and adds the corresponding name-value pair to the message body: for example,

StreamMessage  outMsg = mySession.createMapMessage();
outMsg.setInt("The Meaning of Life", 42);
Table 2–11 Map Message Composition Methods

Name 

Description 

setInt

Store integer in message map by name 

setByte

Store byte value in message map by name 

setBytes

Store byte array in message map by name 

setShort

Store short integer in message map by name 

setLong

Store long integer in message map by name 

setFloat

Store floating-point value in message map by name 

setDouble

Store double-precision value in message map by name 

setBoolean

Store boolean value in message map by name 

setChar

Store character in message map by name 

setString

Store string in message map by name 

setObject

Store object in message map by name 

Like stream messages, map messages provide a convenience method (setObject) for dealing with values whose type is determined dynamically at execution time: for example, the statements

Integer  meaningOfLife = new Integer(42);
outMsg.setObject("The Meaning of Life", meaningOfLife);

are equivalent to

outMsg.setInt("The Meaning of Life", 42);

The object supplied must be either a string object (class String) or an objectified primitive value of class Integer, Byte , Short, Long, Float, Double, Boolean, or Character; otherwise an exception (MessageFormatException) will be thrown.

Composing Object Messages

The ObjectMessage interface provides just one method, setObject (Table 2–12 ), for setting the body of an object message:

ObjectMessage  outMsg = mySession.createObjectMessage();
outMsg.setObject(bodyObject);

The argument to this method can be any serializable object (that is, an instance of any class that implements the standard Java interface Serializable). If the object is not serializable, the exception MessageFormatException will be thrown.

Table 2–12 Object Message Composition Method

Name 

Description 

setObject

Serialize object to message body 

As an alternative, you can initialize the message body directly when you create the message, by passing an object to the session method createObjectMessage:

ObjectMessage  outMsg = mySession.createObjectMessage(bodyObject);

Again, an exception will be thrown if the object is not serializable.

Composing Bytes Messages

The body of a bytes message simply consists of a stream of uninterpreted bytes; its interpretation is entirely a matter of agreement between sender and receiver. This type of message is intended primarily for encoding message formats required by other existing message systems; Message Queue clients should generally use one of the other, more specific message types instead.

Composing a bytes message is similar to composing a stream message (see Composing Stream Messages). You create the message with the session method createBytesMessage, then use the methods shown in Table 2–13 to encode primitive values into the message’s byte stream: for example,

BytesMessage  outMsg = mySession.createBytesMessage();
outMsg.writeUTF("The Meaning of Life");
outMsg.writeInt(42);
Table 2–13 Bytes Message Composition Methods

Name 

Description 

writeInt

Write integer to message stream 

writeByte

Write byte value to message stream 

writeBytes

Write byte array to message stream 

writeShort

Write short integer to message stream 

writeLong

Write long integer to message stream 

writeFloat

Write floating-point value to message stream 

writeDouble

Write double-precision value to message stream 

writeBoolean

Write boolean value to message stream 

writeChar

Write character to message stream 

writeUTF

Write UTF-8 string to message stream 

writeObject

Write value of object to message stream 

reset

Reset message stream 

As with stream and map messages, you can use the generic object-based method writeObject to handle values whose type is unknown at compilation time: for example, the statements

Integer  meaningOfLife = new Integer(42);
outMsg.writeObject(meaningOfLife);

are equivalent to

outMsg.writeInt(42);

The message’s reset method

outMsg.reset();

puts the message body in read-only mode and repositions the byte stream to the beginning, ready to read (see Processing Messages). Attempting to write further content to a message in this state will cause an exception (MessageNotWriteableException). The inherited Message method clearBody can be used to delete the entire message body and make it writeable again.