Package org.objectweb.joram.client.jms

Class MessageConsumer

java.lang.Object

org.objectweb.joram.client.jms.MessageConsumer

All Implemented Interfaces:

AutoCloseable, MessageConsumer

Direct Known Subclasses:

QueueReceiver, TopicSubscriber

public class MessageConsumer
extends Object
implements MessageConsumer

Implements the javax.jms.MessageConsumer interface.

A client uses a MessageConsumer object to receive messages from a destination. A MessageConsumer object is created by calling the createConsumer method on a session object. A message consumer is normally dedicated to a unique destination.
A message consumer can be created with a message selector. A message selector allows the client to restrict the messages delivered to the message consumer to those that match the selector.
A client may either synchronously receive a message consumer's messages or have the consumer asynchronously deliver them as they arrive:

• For synchronous receipt, a client can request the next message from the message consumer using one of its receive methods. There are several variations of receive that allow a client to poll or wait for the next message.
• For asynchronous delivery, a client must register a MessageListener object with a message consumer. As messages arrive at the message consumer, it delivers them by calling the MessageListener's onMessage method. It is a client programming error for a MessageListener to throw an exception.

It is a client programming error for a MessageListener to throw an exception.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) class	MessageConsumer.Closer	This class synchronizes the close.
private static class	MessageConsumer.Status	Status of the message consumer.

Field Summary

Fields

Modifier and Type	Field	Description
private MessageConsumer.Closer	closer	Used to synchronize the method close()
protected Destination	dest	The destination the consumer gets its messages from.
private boolean	durableSubscriber	true for a durable subscriber.
private static org.objectweb.util.monolog.api.Logger	logger
private MessageListener	messageListener
protected boolean	noLocal	true if the subscriber does not wish to consume messages produced by its connection.
(package private) boolean	queueMode	true if the consumer is a queue consumer.
(package private) String	selector	The selector for filtering messages.
protected Session	sess	The session the consumer belongs to.
private boolean	shared
private int	status	Status of the message consumer OPEN, CLOSE
(package private) String	targetName	The consumer server side target is either a queue or a subscription on its proxy.

Constructor Summary

Constructors

Constructor	Description
MessageConsumer(Session sess, Destination dest, String selector)	Constructs a consumer.
MessageConsumer(Session sess, Destination dest, String selector, String subName, boolean noLocal, boolean shared, boolean durableSubscriber)	Constructs a consumer.

Method Summary

Modifier and Type	Method	Description
protected void	checkClosed()
void	close()	API method.
(package private) void	doClose()
Destination	getDest()
MessageListener	getMessageListener()	API method.
String	getMessageSelector()	API method.
boolean	getQueueMode()
String	getTargetName()
boolean	isOpen()
boolean	isQueueMode()
Message	receive()	API method.
Message	receive(long timeOut)	API method.
Message	receiveNoWait()	API method.
void	setMessageListener(MessageListener messageListener)	Sets the message consumer's MessageListener.
private void	setStatus(int status)
String	toString()	Returns a string view of this consumer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

private static org.objectweb.util.monolog.api.Logger logger

selector

String selector

The selector for filtering messages.

durableSubscriber

private boolean durableSubscriber

true for a durable subscriber.

dest

protected Destination dest

The destination the consumer gets its messages from.

noLocal

protected boolean noLocal

true if the subscriber does not wish to consume messages produced by its connection.

sess

protected Session sess

The session the consumer belongs to.

targetName

String targetName

The consumer server side target is either a queue or a subscription on its proxy.

queueMode

boolean queueMode

true if the consumer is a queue consumer.

status

private int status

Status of the message consumer OPEN, CLOSE

closer

private MessageConsumer.Closer closer

Used to synchronize the method close()

shared

private boolean shared

messageListener

private MessageListener messageListener

Constructor Detail

MessageConsumer

MessageConsumer(Session sess,
                Destination dest,
                String selector,
                String subName,
                boolean noLocal,
                boolean shared,
                boolean durableSubscriber)
         throws JMSException

Constructs a consumer.

Parameters:

sess - The session the consumer belongs to.

dest - The destination the consumer gets messages from.

selector - Selector for filtering messages.

subName - The durableSubscriber subscription's name, if any.

noLocal - true for a subscriber not wishing to consume messages produced by its connection.

shared - true if shared consumer.

durableSubscriber - true if durable

Throws:

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - If the selector syntax is invalid.

IllegalStateException - If the connection is broken, or if the subscription is durable and already activated.

JMSException - Generic exception.

MessageConsumer

MessageConsumer(Session sess,
                Destination dest,
                String selector)
         throws JMSException

Constructs a consumer.

Parameters:

sess - The session the consumer belongs to.

dest - The destination the consumer gets messages from.

selector - Selector for filtering messages.

Throws:

InvalidDestinationException - if an invalid destination is specified.

InvalidSelectorException - If the selector syntax is invalid.

IllegalStateException - If the connection is broken, or if the subscription is durable and already activated.

JMSException - Generic exception.

Method Detail

setStatus

private void setStatus(int status)

getTargetName

public final String getTargetName()

getQueueMode

public final boolean getQueueMode()

checkClosed

protected void checkClosed()
                    throws IllegalStateException

Throws:

IllegalStateException

toString

public String toString()

Returns a string view of this consumer.

Overrides:

toString in class Object

setMessageListener

public void setMessageListener(MessageListener messageListener)
                        throws JMSException

Sets the message consumer's MessageListener. API method.

This method must not be called if the connection the consumer belongs to is started, because the session would then be accessed by the thread calling this method and by the thread controlling asynchronous deliveries. This situation is clearly forbidden by the single threaded nature of sessions. Moreover, unsetting a message listener without stopping the connection may lead to the situation where asynchronous deliveries would arrive on the connection, the session or the consumer without being able to reach their target listener!

Specified by:

setMessageListener in interface MessageConsumer

Parameters:

messageListener - the listener to which the messages are to be delivered.

Throws:

IllegalStateException - If the consumer is closed, or if the connection is broken.

JMSException - If the request fails for any other reason.

getMessageListener

public MessageListener getMessageListener()
                                   throws JMSException

API method. Gets the message consumer's MessageListener.

Specified by:

getMessageListener in interface MessageConsumer

Returns:

the listener for the message consumer, or null if no listener is set.

Throws:

IllegalStateException - If the consumer is closed.

JMSException

getMessageSelector

public final String getMessageSelector()
                                throws JMSException

API method. Gets this message consumer's message selector expression.

Specified by:

getMessageSelector in interface MessageConsumer

Returns:

this message consumer's message selector, or null if no message selector is set.

Throws:

IllegalStateException - If the consumer is closed.

JMSException

receive

public Message receive(long timeOut)
                throws JMSException

API method. Receives the next message that arrives before the specified timeout.

This call blocks until a message is available, the timeout expires, or this message consumer is closed. A timeout of zero never expires, and the call blocks indefinitely.

Specified by:

receive in interface MessageConsumer

Parameters:

timeOut - the timeout value (in milliseconds).

Returns:

the next message available for this message consumer, or null if the timeout expires or this message consumer is concurrently closed.

Throws:

IllegalStateException - If the consumer is closed, or if the connection is broken.

JMSSecurityException - If the requester is not a READER on the destination.

JMSException - If the request fails for any other reason.

receive

public Message receive()
                throws JMSException

API method. Receives the next message produced for this message consumer, this call blocks indefinitely until a message is available or until this message consumer is closed.

If this receive is done within a transaction, the consumer retains the message until the transaction commits.

Specified by:

receive in interface MessageConsumer

Returns:

the next message available for this message consumer, or null if this message consumer is concurrently closed.

Throws:

IllegalStateException - If the consumer is closed, or if the connection is broken.

JMSSecurityException - If the requester is not a READER on the destination.

JMSException - If the request fails for any other reason.

receiveNoWait

public Message receiveNoWait()
                      throws JMSException

API method. Receives the next message if one is immediately available.

Specified by:

receiveNoWait in interface MessageConsumer

Returns:

the next message available for this message consumer, or null if none is available.

Throws:

IllegalStateException - If the consumer is closed, or if the connection is broken.

JMSSecurityException - If the requester is not a READER on the destination.

JMSException - If the request fails for any other reason.

close

public void close()
           throws JMSException

API method. Closes the message consumer.

In order to free significant resources allocated on behalf of a MessageConsumer, clients should close them when they are not needed.

This call blocks until a receive or message listener in progress has completed. A blocked message consumer receive call returns null when this message consumer is closed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface MessageConsumer

Throws:

JMSException - if closing the consumer fails due to some internal error.

doClose

void doClose()
      throws JMSException

Throws:

JMSException

getDest

public Destination getDest()

isQueueMode

public boolean isQueueMode()

isOpen

public boolean isOpen()