javax.jms
Interface MessageConsumer

All Known Subinterfaces:
QueueReceiver, TopicSubscriber
public abstract interface MessageConsumer

The parent interface for all message consumers.

A client uses a message consumer to receive messages from a Destination. It is created by passing a Destination to a create message consumer method supplied by a Session.

A message consumer can be created with a message selector. This allows the client to restrict the messages delivered to the message consumer to those that match the selector.

Although a session allows the creation of multiple message consumer's per Destination, it will only deliver each message for a Destination to one message consumer. If more than one message consumer could receive it, the session randomly selects one to deliver it to.

A client may either synchronously receive a message consumer's messages or have the consumer asynchronously deliver them as they arrive.

A client can request the next message from a 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.

A client can 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.

Version:
1.0 - 13 March 1998
Author:
Mark Hapner, Rich Burridge
See Also:
QueueReceiver, TopicSubscriber

Method Summary
 void close()
          Since a provider may allocate some resources on behalf of a MessageConsumer outside the JVM, clients should close them when they are not needed.
 MessageListener getMessageListener()
          Get the message consumer's MessageListener.
 java.lang.String getMessageSelector()
          Get this message consumer's message selector expression.
 Message receive()
          Receive the next message produced for this message consumer.
 Message receive(long timeOut)
          Receive the next message that arrives within the specified timeout interval.
 Message receiveNoWait()
          Receive the next message if one is immediately available.
 void setMessageListener(MessageListener listener)
          Set the message consumer's MessageListener.
 

Method Detail

getMessageSelector


public java.lang.String getMessageSelector()

                                    throws JMSException
Get this message consumer's message selector expression.
Returns:
this message consumer's message selector
Throws:
JMSException - if JMS fails to get message selector due to some JMS error

getMessageListener


public MessageListener getMessageListener()

                                   throws JMSException
Get the message consumer's MessageListener.
Returns:
the listener for the message consumer, or null if this isn't one set.
Throws:
JMSException - if JMS fails to get message listener due to some JMS error
See Also:
setMessageListener(javax.jms.MessageListener)

setMessageListener


public void setMessageListener(MessageListener listener)

                        throws JMSException
Set the message consumer's MessageListener.
Parameters:
messageListener - the messages are delivered to this listener
Throws:
JMSException - if JMS fails to set message listener due to some JMS error
See Also:
getMessageListener()

receive


public Message receive()

                throws JMSException
Receive the next message produced for this message consumer.

This call blocks indefinitely until a message is produced.

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

Returns:
the next message produced for this message consumer.
Throws:
JMSException - if JMS fails to receive the next message due to some error.

receive


public Message receive(long timeOut)

                throws JMSException
Receive the next message that arrives within the specified timeout interval.

This call blocks until either a message arrives or the timeout expires.

Parameters:
timeout - the timeout value (in milliseconds)
Returns:
the next message produced for this message consumer, or null if one is not available.
Throws:
JMSException - if JMS fails to receive the next message due to some error.

receiveNoWait


public Message receiveNoWait()

                      throws JMSException
Receive the next message if one is immediately available.
Returns:
the next message produced for this message consumer, or null if one is not available.
Throws:
JMSException - if JMS fails to receive the next message due to some error.

close


public void close()

           throws JMSException
Since a provider may allocate some resources on behalf of a MessageConsumer outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.
Throws:
JMSException - if JMS fails to close the consumer due to some error.