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:

ClientSession.createConsumer(String)

Method Summary

Modifier and Type	Method and Description
void	close() Closes the consumer.
ConsumerContext	getConsumerContext() The server's ID associated with this 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.
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 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

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