Package org.apache.activemq.artemis.api.core.client

Interface ClientConsumer

All Superinterfaces:
AutoCloseable
public interface ClientConsumer extends AutoCloseable
A ClientConsumer receives messages from ActiveMQ Artemis 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 ActiveMQException if its receive() methods are called.

See Also:

  • Method Details

    • getConsumerContext

      ConsumerContext getConsumerContext()
      The server's ID associated with this consumer. ActiveMQ Artemis implements this as a long but this could be protocol dependent.

    • receive

      ClientMessage receive() throws ActiveMQException
      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 an ActiveMQException.

      Returns:
      a ClientMessage
      Throws:
      ActiveMQException - if an exception occurs while waiting to receive a message

    • receive

      ClientMessage receive(long timeout) throws ActiveMQException
      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 an ActiveMQException.

      Parameters:
      timeout - time (in milliseconds) to wait to receive a message
      Returns:
      a message or null if the time out expired
      Throws:
      ActiveMQException - if an exception occurs while waiting to receive a message

    • receiveImmediate

      ClientMessage receiveImmediate() throws ActiveMQException
      Receives a message from a queue. This call will force a network trip to ActiveMQ Artemis 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 an ActiveMQException.

      Returns:
      a message or null if there are no messages in the queue for this consumer
      Throws:
      ActiveMQException - if an exception occurs while waiting to receive a message

    • getMessageHandler

      MessageHandler getMessageHandler() throws ActiveMQException
      Calling this method on a closed consumer will throw an ActiveMQException.
      Returns:
      the MessageHandler associated to this consumer or null
      Throws:
      ActiveMQException - if an exception occurs while getting the MessageHandler

    • setMessageHandler

      ClientConsumer setMessageHandler(MessageHandler handler) throws ActiveMQException
      Sets the MessageHandler for this consumer to consume messages asynchronously.

      Note that setting a handler dedicates the parent session, and its child producers and consumers, to the session-wide handler delivery thread of control.

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

      Parameters:
      handler - a MessageHandler
      Throws:
      ActiveMQException - if an exception occurs while setting the MessageHandler

    • close

      void close() throws ActiveMQException
      Closes the consumer.

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

      Specified by:
      close in interface AutoCloseable
      Throws:
      ActiveMQException

    • isClosed

      boolean isClosed()
      Returns true if this consumer is closed, false else.
      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 or null.
      Returns:
      the last exception thrown by a call to this consumer's MessageHandler or null