## 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 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:
    `HornetQException` - if an exception occurs while waiting to receive a message

### receive

    ClientMessage receive(long timeout)
                          throws 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:
    `HornetQException` - if an exception occurs while waiting to receive a message

### receiveImmediate

    ClientMessage receiveImmediate()
                                   throws 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:
    `HornetQException` - if an exception occurs while waiting to receive a message

### getMessageHandler

    MessageHandler getMessageHandler()
                                     throws 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:
    `HornetQException` - if an exception occurs while getting the MessageHandler

### setMessageHandler

    void setMessageHandler(MessageHandler handler)
                           throws 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:
    `HornetQException` - if an exception occurs while setting the MessageHandler

### close

    void close()
               throws HornetQException

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

  Throws:
    `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 © 2009 Red Hat Inc. All Rights Reserved.