org.hornetq.api.core.client
Interface ClientConsumer

public interface ClientConsumer

A ClientConsumer receives messages from HornetQ queues.
Messages can be consumed synchronously by using the receive() methods which will block until a message is received (or a timeout expires) or asynchronously by setting a MessageHandler.
These 2 types of consumption are exclusive: a ClientConsumer with a MessageHandler set will throw HornetQException if its receive() methods are called.

Author:

Tim Fox, Clebert Suconic, Andy Taylor

See Also:

ClientSession.createConsumer(String)

Method Summary

void	close() Closes the consumer.
Exception	getLastException() Returns the last exception thrown by a call to this consumer's MessageHandler.
MessageHandler	getMessageHandler() Returns the MessageHandler associated to this consumer.
boolean	isClosed() Returns whether the consumer is closed or not.
ClientMessage	receive() Receives a message from a queue.
ClientMessage	receive(long timeout) Receives a message from a queue.
ClientMessage	receiveImmediate() Receives a message from a queue.
void	setMessageHandler(MessageHandler handler) Sets the MessageHandler for this consumer to consume messages asynchronously.

Method Detail

receive

ClientMessage receive()
                      throws org.hornetq.api.core.HornetQException

Receives a message from a queue.

This call will block indefinitely until a message is received.

Calling this method on a closed consumer will throw a HornetQException.

Returns:

a ClientMessage

Throws:

org.hornetq.api.core.HornetQException - if an exception occurs while waiting to receive a message

receive

ClientMessage receive(long timeout)
                      throws org.hornetq.api.core.HornetQException

Receives a message from a queue.

This call will block until a message is received or the given timeout expires.

Calling this method on a closed consumer will throw a HornetQException.

Parameters:

timeout - time (in milliseconds) to wait to receive a message

Returns:

a message or null if the time out expired

Throws:

org.hornetq.api.core.HornetQException - if an exception occurs while waiting to receive a message

receiveImmediate

ClientMessage receiveImmediate()
                               throws org.hornetq.api.core.HornetQException

Receives a message from a queue. This call will force a network trip to HornetQ server to ensure that there are no messages in the queue which can be delivered to this consumer.

This call will never wait indefinitely for a message, it will return null if no messages are available for this consumer.

Note however that there is a performance cost as an additional network trip to the server may required to check the queue status.

Calling this method on a closed consumer will throw a HornetQException.

Returns:

a message or null if there are no messages in the queue for this consumer

Throws:

org.hornetq.api.core.HornetQException - if an exception occurs while waiting to receive a message

getMessageHandler

MessageHandler getMessageHandler()
                                 throws org.hornetq.api.core.HornetQException

Returns the MessageHandler associated to this consumer.

Calling this method on a closed consumer will throw a HornetQException.

Returns:

the MessageHandler associated to this consumer or null

Throws:

org.hornetq.api.core.HornetQException - if an exception occurs while getting the MessageHandler

setMessageHandler

void setMessageHandler(MessageHandler handler)
                       throws org.hornetq.api.core.HornetQException

Sets the MessageHandler for this consumer to consume messages asynchronously. Calling this method on a closed consumer will throw a HornetQException.

Parameters:

handler - a MessageHandler

Throws:

org.hornetq.api.core.HornetQException - if an exception occurs while setting the MessageHandler

close

void close()
           throws org.hornetq.api.core.HornetQException

Closes the consumer.

Once this consumer is closed, it can not receive messages, whether synchronously or asynchronously.

Throws:

org.hornetq.api.core.HornetQException

isClosed

boolean isClosed()

Returns whether the consumer is closed or not.

Returns:

true if this consumer is closed, false else

getLastException

Exception getLastException()

Returns the last exception thrown by a call to this consumer's MessageHandler.

Returns:

the last exception thrown by a call to this consumer's MessageHandler or null