Sun GlassFish Message Queue 4.4 Developer's Guide for Java Clients

Creating Message Consumers

The session method createConsumer creates a generic consumer that can be used to receive messages from either a (point-to-point) queue or a (publish/subscribe) topic:

MessageConsumer  myConsumer = mySession.createConsumer(myDest);

If the destination is a queue, the consumer is called a receiver for that queue; if it is a topic, the consumer is a subscriber to that topic.


Note –

The generic MessageConsumer interface also has specialized subinterfaces, QueueReceiver and TopicSubscriber, for receiving messages specifically from a point-to-point queue or a publish/subscribe topic. These types of consumer are created by the createReceiver and createSubscriber 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 consumer described here, which can handle both types of destination indiscriminately.


A subscriber created for a topic destination with the createConsumer method is always nondurable, meaning that it will receive only messages that are sent (published)to the topic while the subscriber is active. If you want the broker to retain messages published to a topic while no subscriber is active and deliver them when one becomes active again, you must instead create a durable subscriber, as described in Durable Subscribers.

Table 2–15 shows the methods defined in the MessageConsumer interface, which are discussed in detail in the relevant sections below.

Table 2–15 Message Consumer Methods

Name 

Description 

getMessageSelector

Get message selector 

receive

Receive message synchronously 

receiveNoWait

Receive message synchronously without blocking 

setMessageListener

Set message listener for asynchronous reception 

getMessageListener

Get message listener for asynchronous reception 

close

Close message consumer 

Message Selectors

If appropriate, you can restrict the messages a consumer will receive from its destination by supplying a message selector as an argument when you create the consumer:

String  mySelector = "/* Text of selector here */";
MessageConsumer  myConsumer = mySession.createConsumer(myDest, mySelector);

The selector is a string whose syntax is based on a subset of the SQL92 conditional expression syntax, which allows you to filter the messages you receive based on the values of their properties (see Message Properties). See the Java Message Service Specification for a complete description of this syntax. The message consumer’s getMessageSelector method returns the consumer’s selector string (or null if no selector was specified when the consumer was created):

String  mySelector = myConsumer.getMessageSelector();

Note –

Messages whose properties do not satisfy the consumer’s selector will be retained undelivered by the destination until they are retrieved by another message consumer. The use of message selectors can thus cause messages to be delivered out of sequence from the order in which they were originally produced. Only a message consumer without a selector is guaranteed to receive messages in their original order.


In some cases, the same connection may both publish and subscribe to the same topic destination. The createConsumer method accepts an optional boolean argument that suppresses the delivery of messages published by the consumer’s own connection:

String  mySelector = "/* Text of selector here */";
MessageConsumer
        myConsumer = mySession.createConsumer(myDest, mySelector, true);

The resulting consumer will receive only messages published by a different connection.

Durable Subscribers

To receive messages delivered to a publish/subscribe topic while no message consumer is active, you must ask the message broker to create a durable subscriber for that topic. All sessions that create such subscribers for a given topic must have the same client identifier (see Using Connections ). When you create a durable subscriber, you supply a subscriber name that must be unique for that client identifier:

MessageConsumer
        myConsumer = mySession.createDurableSubscriber(myDest, "mySub");

(The object returned by the createDurableSubscriber method is actually typed as TopicSubscriber, but since that is a subinterface of MessageConsumer, you can safely assign it to a MessageConsumer variable. Note, however, that the destination myDest must be a publish/subscribe topic and not a point-to-point queue.)

You can think of a durable subscriber as a “virtual message consumer” for the specified topic, identified by the unique combination of a client identifier and subscriber name. When a message arrives for the topic and no message consumer is currently active for it, the message will be retained for later delivery. Whenever you create a consumer with the given client identifier and subscriber name, it will be considered to represent this same durable subscriber and will receive all of the accumulated messages that have arrived for the topic in the subscriber’s absence. Each message is retained until it is delivered to (and acknowledged by) such a consumer or until it expires.


Note –

Only one session at a time can have an active consumer for a given durable subscription. If another such consumer already exists, the createDurableSubscriber method will throw an exception.


Like the createConsumer method described in the preceding section (which creates nondurable subscribers), createDurableSubscriber can accept an optional message selector string and a boolean argument telling whether to suppress the delivery of messages published by the subscriber’s own connection:

String  mySelector = "/* Text of selector here */";
MessageConsumer  myConsumer
                    = mySession.createDurableSubscriber(myDest, "mySub",
                                                        mySelector, true);

You can change the terms of a durable subscription by creating a new subscriber with the same client identifier and subscription name but with a different topic, selector, or both. The effect is as if the old subscription were destroyed and a new one created with the same name. When you no longer need a durable subscription, you can destroy it with the session method unsubscribe:

mySession.unsubscribe("mySub");