Consuming a Message

Messages are received by a message consumer, within the context of a connection
and session. A client uses a message consumer object (MessageConsumer) to receive
messages from a specified physical destination, represented in the API as a destination
object.

When you create a consumer, you specify the destination from which it consumes
messages.

Three factors affect how the broker delivers messages to a consumer:

Whether consumption is synchronous or asynchronous

Whether a selector is used to filter incoming messages

If messages are consumed from a topic destination, whether the subscriber is durable

These factors are described in the following sections.

Another factor that affects message delivery, the degree of reliability required by the
messaging application, is described in Reliable Message Delivery.

Synchronous and Asynchronous Consumers

A message consumer can support either synchronous or asynchronous consumption of messages.

Synchronous consumption means the consumer explicitly requests a message that has been delivered to the client runtime and then consumes it.

Depending on the method used to request messages, a synchronous consumer can choose to wait (indefinitely) until a message is delivered to the client runtime, to wait a specified amount of time for a message, or to return immediately if there is no message available to be consumed (messages that were successfully produced but which the broker has not finished processing).

Asynchronous consumption means that the message is automatically handed off to a message listener object (MessageListener) that has been registered with the consumer. The client consumes the message when a session thread invokes the onMessage() method of the message listener object.

Using Selectors to Filter Messages

A message consumer can use a message selector to have the message
service deliver only those messages whose properties (see Message Properties) match specific selection criteria.
You specify this criteria when you create the consumer.

Selectors use an SQL-like syntax to match against message properties. For example,

color = ”red’
size > 10

Java clients can also specify selectors when browsing a queue; this allows you
to see which selected messages are waiting to be consumed.

Using Durable Subscribers

A durable subscriber is one for which the broker retains messages even when
the subscriber becomes inactive.

Because the broker must maintain state for the subscriber and resume delivery of
messages when the subscriber is reactivated, the broker must be able to identify
a given subscriber throughout its comings and goings. The subscriber’s identity is constructed
from the ClientID property of the connection that created it and the subscriber
name specified when you create the subscriber.