Creating Message Consumers
A MessageConsumer object can be used to receive messages from a queue or for a specific topic. The common MessageConsumer interface behaves in the same manner as its respective sub‑interfaces QueueReceiver and TopicSubscriber, which are PTP- and pub/sub-specific interfaces.
To create a message consumer in a Session, call the session.createConsumer(...) method and pass in a queue or topic destination.
To create a message consumer in an XA Session, rather than a non‑transacted local Session, call the XASession.createConsumer(...) method and pass in queue or topic.
Once a message consumer is created, it becomes active and can be used to receive messages on a connection that is started. Call close() to close the message consumer.
Message Consumer Durability
When consuming messages from a queue, the durability of the message consumer depends on the durability of the queue. For example, if the queue is durable, then the message consumer is also durable. For more information on the durability of destinations, refer to Working with Destinations.
When consuming messages for a given topic, the created topic subscriber is always non‑durable. That is, the implicitly‑created subscriber can only receive messages published to the topic when it is connected; messages are not spooled when the subscriber disconnects.
If you want to create a durable topic subscriber, you can use the createDurableSubscriber(...) method (refer to Creating Durable Topic Subscribers).
For durable consumers and durable topic subscribers, the clients are bound to the durable queue and topic-endpoint.
For non-durable consumers (that is, consumers bound to temporary queues and non‑durable topic subscribers), temporary topic-endpoints and queues are automatically created for the consumers.
Selectively Receiving Messages
A message consumer can also use the following features to fine-tune the messages it will receive:
messageSelector—A message selector can be passed in to restrict the messages that are delivered when a Guaranteed Transport mode is used. A message selector uses header field references and property references to specify what messages a message consumer is interested in. For more information, refer to Selectors.noLocal—ThenoLocalattribute can be enabled to prevent the delivery of messages published on the same connection used by the consumer. For example, it is possible that on a single connection, a client publishes messages to the same Topic that it is consuming messages for.
To create a durable MessageConsumer with a message selector and the noLocal attribute, call the createConsumer(Destination destination, java.lang.String messageSelector, boolean noLocal) method.
When the Direct Transport mode is used, a message selector or the NoLocal attribute cannot be used when a non-durable consumer is created. A configuration exception is returned.
Receiving Active/Inactive Indications for Exclusive Queue Consumers
When a queue has an exclusive access type, multiple message consumers can be bound to that queue, but only one message consumer can actively receive messages.
If you want to receive notifications as to whether a message consumer that is bound to a queue is actively receiving messages (that is, it has an active flow) or if it is not actively receiving messages (that is, it has an inactive flow), you can use a Solace-specific com.solacesystems.jms.SolEventSource interface that allows JMS applications to register event listeners for events of interest, such as active flow indication.
From this interface, call addSolEventListener(...) and pass in an SolEventListener that the client application can use to handle any returned SolEvents that indicate whether the message consumer has an active or inactive flow to a queue.
The com.solacesystems.jms.SolEventListener interface relies on the following method to handle SolEvents:
com.solacesystems.jms.SolEventListener.handleEvent(SolEventSource source, SolEvent event)
Where:
SolEventSource is the source of the SolEvents. For active flow indications, this is the message consumer.
SolEvent is the Solace proprietary event that is returned. For active flow indications, it is an ActiveFlowIndicationEvent that returns one of the following constants that indicate whether the message consumer has an active flow:
- 0—Flow is inactive
- 1—Flow is active
To de-register or remove the SolEventListener instance, call remove.
SolEventListener()
The following code snippet shows how to use the SolEvent JMS interface to receive active/inactive flow indications for exclusive queue consumers:
// session is a valid javax.jms.Session and queue is a valid javax.jms.Queue
consumer = session.createConsumer(queue);
try {
SolEventSource evtSource = (SolEventSource)consumer;
evtSource.addSolEventListener(new SolEventListener() {
public void handleEvent(SolEventSource source, SolEvent evt) {
ActiveFlowIndicationEvent afiEvent =
(ActiveFlowIndicationEvent) evt;
if (evt.getFlowState() ==
ActiveFlowIndicationEvent. FLOW_ACTIVE) {
// Take action here
}
}
}, SolEvent.SOLEVENT_TYPE_ACTIVE_FLOW_INDICATION);
} catch (ClassCastExcetpion ex) {
ex.printStackTrace();
}
Related Sample
For a more complete example of how to use the SolEvent JMS interface to receive active/inactive flow indications for exclusive queue consumers, refer to the SolJMSActiveFlowIndication sample.