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 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