io.openmessaging.consumer

Interface PullConsumer

All Superinterfaces:

Client, Consumer, Extension, ServiceLifecycle

public interface PullConsumer
extends Consumer

A PullConsumer pulls messages from the specified queue, and supports submit the consume result by acknowledgement.

Since:

OMS 1.0.0

Version:

OMS 1.0.0

See Also:

MessagingAccessPoint.createPullConsumer()

Method Summary

Modifier and Type	Method and Description
void	ack(MessageReceipt receiptHandle) Acknowledges the specified and consumed message with the unique message receipt handle.
List<Message>	batchReceive(long timeout) Receive message in asynchronous way.
List<Message>	batchReceive(String queueName, QueueMetaData queueMetaData, MessageReceipt messageReceipt, long timeout) Receive message in asynchronous way.
void	bindQueue(Collection<String> queueNames) Bind the Consumer to a collection of queue in pull model, user can use receive(long) to get messages from a collection of queue.
Message	receive() Receives the next message from the attached queues of this consumer.
Message	receive(long timeout) Receives the next message from the bind queues of this consumer in pull model.
Message	receive(String queueName, QueueMetaData queueMetaData, MessageReceipt messageReceipt, long timeout) Receives the next message from the which bind queue,partition and receiptId of this consumer in pull model.
void	unbindQueue(Collection<String> queueNames) Unbind the Consumer from a collection of queues.

Methods inherited from interface io.openmessaging.consumer.Consumer

addInterceptor, getBindQueues, removeInterceptor

Methods inherited from interface io.openmessaging.ServiceLifecycle

currentState, start, stop

Methods inherited from interface io.openmessaging.extension.Extension

getQueueMetaData

Methods inherited from interface io.openmessaging.Client

getExtension

Method Detail

bindQueue

void bindQueue(Collection<String> queueNames)

Bind the Consumer to a collection of queue in pull model, user can use receive(long) to get messages from a collection of queue.

Parameters:

queueNames - a collection of queues.

Throws:

OMSSecurityException - when have no authority to bind to this queue.

OMSDestinationException - when have no given destination in the server.

OMSRuntimeException - when the Producer fails to send the message due to some internal error.

unbindQueue

void unbindQueue(Collection<String> queueNames)

Unbind the Consumer from a collection of queues.

After the success call, this consumer won't receive new message from the specified queue any more.

Parameters:

queueNames - a collection of queues.

receive

Message receive()

Receives the next message from the attached queues of this consumer.

This call blocks indefinitely until a message is arrives, the timeout expires, or until this PullConsumer is shut down.

Returns:

the next message received from the attached queues, or null if the consumer is concurrently shut down or the timeout expires

Throws:

OMSRuntimeException - if the consumer fails to pull the next message due to some internal error.

receive

Message receive(long timeout)

Receives the next message from the bind queues of this consumer in pull model.

This call blocks indefinitely until a message is arrives, the timeout expires, or until this PullConsumer is shut down.

Parameters:

timeout - receive message will blocked at most timeout milliseconds.

Returns:

the next message received from the bind queues, or null if the consumer is concurrently shut down.

Throws:

OMSSecurityException - when have no authority to receive messages from this queue.

OMSTimeOutException - when the given timeout elapses before the send operation completes.

OMSRuntimeException - when the Producer fails to send the message due to some internal error.

receive

@Optional
Message receive(String queueName,
                          QueueMetaData queueMetaData,
                          MessageReceipt messageReceipt,
                          long timeout)

Receives the next message from the which bind queue,partition and receiptId of this consumer in pull model.

This call blocks indefinitely until a message is arrives, the timeout expires, or until this PullConsumer is shut down.

Parameters:

queueName - receive message from which queueName in Message Queue.

queueMetaData - receive message from which partition in Message Queue.

messageReceipt - receive message from which receipt position in Message Queue.

timeout - receive message will blocked at most timeout milliseconds.

Returns:

the next message received from the bind queues, or null if the consumer is concurrently shut down.

Throws:

OMSSecurityException - when have no authority to receive messages from this queue.

OMSTimeOutException - when the given timeout elapses before the send operation completes.

OMSRuntimeException - when the Producer fails to send the message due to some internal error.

batchReceive

List<Message> batchReceive(long timeout)

Receive message in asynchronous way. This call doesn't block user's thread, and user's message resolve logic should implement in the MessageListener.

Parameters:

timeout - receive messages will blocked at most timeout milliseconds.

Returns:

the next batch messages received from the bind queues, or null if the consumer is concurrently shut down.

Throws:

OMSSecurityException - when have no authority to receive messages from this queue.

OMSTimeOutException - when the given timeout elapses before the send operation completes.

OMSRuntimeException - when the Producer fails to send the message due to some internal error.

batchReceive

@Optional
List<Message> batchReceive(String queueName,
                                     QueueMetaData queueMetaData,
                                     MessageReceipt messageReceipt,
                                     long timeout)

Receive message in asynchronous way. This call doesn't block user's thread, and user's message resolve logic should implement in the MessageListener.

Parameters:

queueName - receive message from which queueName in Message Queue.

queueMetaData - receive message from which partition in Message Queue.

messageReceipt - receive message from which receipt position in Message Queue.

timeout - receive messages will blocked at most timeout milliseconds.

Returns:

the next batch messages received from the bind queues, or null if the consumer is concurrently shut down.

Throws:

OMSSecurityException - when have no authority to receive messages from this queue.

OMSTimeOutException - when the given timeout elapses before the send operation completes.

OMSRuntimeException - when the Producer fails to send the message due to some internal error.

ack

void ack(MessageReceipt receiptHandle)

Acknowledges the specified and consumed message with the unique message receipt handle.

Messages that have been received but not acknowledged may be redelivered.

Specified by:

ack in interface Consumer

Parameters:

receiptHandle - the receipt handle associated with the consumed message

Throws:

OMSRuntimeException - if the consumer fails to acknowledge the messages due to some internal error.