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

## Interface ClientConsumer

- All Superinterfaces:
    `java.lang.AutoCloseable`

      public interface ClientConsumer
      extends java.lang.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:
    `ClientSession.createConsumer(String)`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Closes the consumer.
    `ConsumerContext` | `getConsumerContext()` | The server's ID associated with this consumer.
    `java.lang.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.
    `ClientConsumer` | `setMessageHandler​(MessageHandler handler)` | Sets the MessageHandler for this consumer to consume messages asynchronously.

- - ### Method Detail

    - #### getConsumerContext

          ConsumerContext getConsumerContext()

      The server's ID associated with this consumer. ActiveMQ Artemis implements this as a long but this could be protocol dependent.
      Returns:

    - #### receive

          ClientMessage receive()
                         throws org.apache.activemq.artemis.api.core.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:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while waiting to receive a message

    - #### receive

          ClientMessage receive​(long timeout)
                         throws org.apache.activemq.artemis.api.core.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:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while waiting to receive a message

    - #### receiveImmediate

          ClientMessage receiveImmediate()
                                  throws org.apache.activemq.artemis.api.core.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:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while waiting to receive a message

    - #### getMessageHandler

          MessageHandler getMessageHandler()
                                    throws org.apache.activemq.artemis.api.core.ActiveMQException

      Returns the MessageHandler associated to this consumer.

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

      Returns:
        the MessageHandler associated to this consumer or `null`
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while getting the MessageHandler

    - #### setMessageHandler

          ClientConsumer setMessageHandler​(MessageHandler handler)
                                    throws org.apache.activemq.artemis.api.core.ActiveMQException

      Sets the MessageHandler for this consumer to consume messages asynchronously.

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

      Parameters:
        `handler` - a MessageHandler
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException` - if an exception occurs while setting the MessageHandler

    - #### close

          void close()
              throws org.apache.activemq.artemis.api.core.ActiveMQException

      Closes the consumer.

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

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `org.apache.activemq.artemis.api.core.ActiveMQException`

    - #### isClosed

          boolean isClosed()

      Returns whether the consumer is closed or not.
      Returns:
        `true` if this consumer is closed, `false` else

    - #### getLastException

          java.lang.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`