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.

In addition,Message Queue consumers can specify symbolic topic destination names that use wildcard characters. Messages are delivered to such wildcard consumers from all destinations that match the symbolic destination name. See Supported Topic Destination Names in Sun GlassFish Message Queue 4.4 Administration Guide.

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.