Sending Messages

In order to send messages to a message broker, you must create a message producer using the session method createProducer:

MessageProducer  myProducer = mySession.createProducer(myDest);

The scope of the message producer is limited to the session that created it and the connection to which that session belongs. Table 2–14 shows the methods defined in the MessageProducer interface.

The createProducer method takes a destination as an argument, which may be either a (point-to-point) queue or a (publish/subscribe) topic. The producer will then send all of its messages to the specified destination. If the destination is a queue, the producer is called a sender for that queue; if it is a topic, the producer is a publisher to that topic. The message producer’s getDestination method returns this destination.

You also have the option of leaving the destination unspecified when you create a producer

MessageProducer  myProducer = mySession.createProducer(null);

in which case you must specify an explicit destination for each message. This option is typically used for producers that must send messages to a variety of destinations, such as those designated in the JMSReplyTo header fields of incoming messages (see Message Header).

The generic MessageProducer interface also has specialized subinterfaces, QueueSender and TopicPublisher, for sending messages specifically to a point-to-point queue or a publish/subscribe topic. These types of producer are created by the createSender and createPublisher methods of the specialized session subinterfaces QueueSession and TopicSession, respectively. However, it is generally more convenient (and recommended) to use the generic form of message producer described here, which can handle both types of destination indiscriminately.

A producer has a default delivery mode (persistent or nonpersistent), priority level, and message lifetime, which it will apply to all messages it sends unless explicitly overridden for an individual message. You can set these properties with the message producer methods setDeliveryMode, setPriority, and setTimeToLive, and retrieve them with getDeliveryMode, getPriority, and getTimeToLive. If you don’t set them explicitly, they default to persistent delivery, priority level 4, and a lifetime value of 0, denoting an unlimited message lifetime.

The heart of the message producer interface is the send method, which is available in a variety of overloaded forms. The simplest of these just takes a message as its only argument:

myProducer.send(outMsg);

This sends the specified message to the producer’s default destination, using the producer’s default delivery mode, priority, and message lifetime. Alternatively, you can explicitly specify the destination

myProducer.send(myDest, outMsg);

or the delivery mode, priority, and lifetime in milliseconds

myProducer.send(outMsg, DeliveryMode.NON_PERSISTENT, 9, 1000);

or all of these at once:

myProducer.send(myDest, outMsg, DeliveryMode.NON_PERSISTENT, 9, 1000);

Recall that if you did not specify a destination when creating the message producer, you must provide an explicit destination for each message you send.

As discussed earlier under Message Header, client applications that have no need for the message identifier and time stamp fields in the message header can gain some performance improvement by suppressing the generation of these fields, using the message producer’s setDisableMessageID and setdisableMessageTimestamp methods. Note that a true value for either of these flags disables the generation of the corresponding header field, while a false value enables it. Both flags are set to false by default, meaning that the broker will generate the values of these header fields unless explicitly instructed otherwise.

When you are finished using a message producer, you should call its close method

myProducer.close();

allowing the broker and client runtime to release any resources they may have allocated on the producer’s behalf.