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


Copyright © 2012 JBoss, a division of Red Hat. All Rights Reserved.