org.apache.pulsar.client.api

接口 Consumer<T>

所有超级接口:

AutoCloseable, Closeable

public interface Consumer<T>
extends Closeable

An interface that abstracts behavior of Pulsar's consumer.

All the operations on the consumer instance are thread safe.

方法概要

限定符和类型	方法和说明
void	acknowledge(Message<?> message) Acknowledge the consumption of a single message
void	acknowledge(MessageId messageId) Acknowledge the consumption of a single message, identified by its MessageId.
CompletableFuture<Void>	acknowledgeAsync(Message<?> message) Asynchronously acknowledge the consumption of a single message
CompletableFuture<Void>	acknowledgeAsync(MessageId messageId) Asynchronously acknowledge the consumption of a single message
void	acknowledgeCumulative(Message<?> message) Acknowledge the reception of all the messages in the stream up to (and including) the provided message.
void	acknowledgeCumulative(MessageId messageId) Acknowledge the reception of all the messages in the stream up to (and including) the provided message.
CompletableFuture<Void>	acknowledgeCumulativeAsync(Message<?> message) Asynchronously Acknowledge the reception of all the messages in the stream up to (and including) the provided message.
CompletableFuture<Void>	acknowledgeCumulativeAsync(MessageId messageId) Asynchronously Acknowledge the reception of all the messages in the stream up to (and including) the provided message.
void	close() Close the consumer and stop the broker to push more messages.
CompletableFuture<Void>	closeAsync() Asynchronously close the consumer and stop the broker to push more messages
String	getConsumerName() Get the name of consumer.
ConsumerStats	getStats() Get statistics for the consumer.
String	getSubscription() Get a subscription for the consumer
String	getTopic() Get a topic for the consumer
boolean	hasReachedEndOfTopic() Return true if the topic was terminated and this consumer has already consumed all the messages in the topic.
boolean	isConnected()
void	negativeAcknowledge(Message<?> message) Acknowledge the failure to process a single message.
void	negativeAcknowledge(MessageId messageId) Acknowledge the failure to process a single message.
void	pause() Stop requesting new messages from the broker until resume() is called.
Message<T>	receive() Receives a single message.
Message<T>	receive(int timeout, TimeUnit unit) Receive a single message Retrieves a message, waiting up to the specified wait time if necessary.
CompletableFuture<Message<T>>	receiveAsync() Receive a single message Retrieves a message when it will be available and completes CompletableFuture with received message.
void	redeliverUnacknowledgedMessages() Redelivers all the unacknowledged messages.
void	resume() Resume requesting messages from the broker.
void	seek(long timestamp) Reset the subscription associated with this consumer to a specific message publish time.
void	seek(MessageId messageId) Reset the subscription associated with this consumer to a specific message id.
CompletableFuture<Void>	seekAsync(long timestamp) Reset the subscription associated with this consumer to a specific message publish time.
CompletableFuture<Void>	seekAsync(MessageId messageId) Reset the subscription associated with this consumer to a specific message id.
void	unsubscribe() Unsubscribe the consumer This call blocks until the consumer is unsubscribed.
CompletableFuture<Void>	unsubscribeAsync() Asynchronously unsubscribe the consumer

方法详细资料

getTopic

String getTopic()

Get a topic for the consumer

返回:

topic for the consumer

getSubscription

String getSubscription()

Get a subscription for the consumer

返回:

subscription for the consumer

unsubscribe

void unsubscribe()
          throws PulsarClientException

Unsubscribe the consumer

This call blocks until the consumer is unsubscribed.

Unsubscribing will the subscription to be deleted and all the data retained can potentially be deleted as well.

The operation will fail when performed on a shared subscription where multiple consumers are currently connected.

抛出:

PulsarClientException - if the operation fails

unsubscribeAsync

CompletableFuture<Void> unsubscribeAsync()

Asynchronously unsubscribe the consumer

返回:

CompletableFuture to track the operation

另请参阅:

unsubscribe()

receive

Message<T> receive()
            throws PulsarClientException

Receives a single message.

This calls blocks until a message is available.

返回:

the received message

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException.InvalidConfigurationException - if a message listener was defined in the configuration

PulsarClientException

receiveAsync

CompletableFuture<Message<T>> receiveAsync()

Receive a single message

Retrieves a message when it will be available and completes CompletableFuture with received message.

receiveAsync() should be called subsequently once returned CompletableFuture gets complete with received message. Else it creates backlog of receive requests in the application.

返回:

CompletableFuture<Message> will be completed when message is available

receive

Message<T> receive(int timeout,
                   TimeUnit unit)
            throws PulsarClientException

Receive a single message

Retrieves a message, waiting up to the specified wait time if necessary.

参数:

timeout - 0 or less means immediate rather than infinite

unit -

返回:

the received Message or null if no message available before timeout

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException.InvalidConfigurationException - if a message listener was defined in the configuration

PulsarClientException

acknowledge

void acknowledge(Message<?> message)
          throws PulsarClientException

Acknowledge the consumption of a single message

参数:

message - The Message to be acknowledged

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException

acknowledge

void acknowledge(MessageId messageId)
          throws PulsarClientException

Acknowledge the consumption of a single message, identified by its MessageId.

参数:

messageId - The MessageId to be acknowledged

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException

negativeAcknowledge

void negativeAcknowledge(Message<?> message)

Acknowledge the failure to process a single message.

When a message is "negatively acked" it will be marked for redelivery after some fixed delay. The delay is configurable when constructing the consumer with ConsumerBuilder.negativeAckRedeliveryDelay(long, TimeUnit).

This call is not blocking.

Example of usage:

 while (true) {
     Message<String> msg = consumer.receive();

     try {
          // Process message...

          consumer.acknowledge(msg);
     } catch (Throwable t) {
          log.warn("Failed to process message");
          consumer.negativeAcknowledge(msg);
     }
 }
 

参数:

message - The Message to be acknowledged

negativeAcknowledge

void negativeAcknowledge(MessageId messageId)

Acknowledge the failure to process a single message.

When a message is "negatively acked" it will be marked for redelivery after some fixed delay. The delay is configurable when constructing the consumer with ConsumerBuilder.negativeAckRedeliveryDelay(long, TimeUnit).

This call is not blocking.

This variation allows to pass a MessageId rather than a Message object, in order to avoid keeping the payload in memory for extended amount of time

参数:

messageId - The MessageId to be acknowledged

另请参阅:

negativeAcknowledge(Message)

acknowledgeCumulative

void acknowledgeCumulative(Message<?> message)
                    throws PulsarClientException

Acknowledge the reception of all the messages in the stream up to (and including) the provided message. This method will block until the acknowledge has been sent to the broker. After that, the messages will not be re-delivered to this consumer. Cumulative acknowledge cannot be used when the consumer type is set to ConsumerShared. It's equivalent to calling asyncAcknowledgeCumulative(Message) and waiting for the callback to be triggered.

参数:

message - The Message to be cumulatively acknowledged

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException

acknowledgeCumulative

void acknowledgeCumulative(MessageId messageId)
                    throws PulsarClientException

Acknowledge the reception of all the messages in the stream up to (and including) the provided message. This method will block until the acknowledge has been sent to the broker. After that, the messages will not be re-delivered to this consumer. Cumulative acknowledge cannot be used when the consumer type is set to ConsumerShared. It's equivalent to calling asyncAcknowledgeCumulative(MessageId) and waiting for the callback to be triggered.

参数:

messageId - The MessageId to be cumulatively acknowledged

抛出:

PulsarClientException.AlreadyClosedException - if the consumer was already closed

PulsarClientException

acknowledgeAsync

CompletableFuture<Void> acknowledgeAsync(Message<?> message)

Asynchronously acknowledge the consumption of a single message

参数:

message - The Message to be acknowledged

返回:

a future that can be used to track the completion of the operation

acknowledgeAsync

CompletableFuture<Void> acknowledgeAsync(MessageId messageId)

Asynchronously acknowledge the consumption of a single message

参数:

messageId - The MessageId to be acknowledged

返回:

a future that can be used to track the completion of the operation

acknowledgeCumulativeAsync

CompletableFuture<Void> acknowledgeCumulativeAsync(Message<?> message)

Asynchronously Acknowledge the reception of all the messages in the stream up to (and including) the provided message. Cumulative acknowledge cannot be used when the consumer type is set to ConsumerShared.

参数:

message - The Message to be cumulatively acknowledged

返回:

a future that can be used to track the completion of the operation

acknowledgeCumulativeAsync

CompletableFuture<Void> acknowledgeCumulativeAsync(MessageId messageId)

Asynchronously Acknowledge the reception of all the messages in the stream up to (and including) the provided message. Cumulative acknowledge cannot be used when the consumer type is set to ConsumerShared.

参数:

messageId - The MessageId to be cumulatively acknowledged

返回:

a future that can be used to track the completion of the operation

getStats

ConsumerStats getStats()

Get statistics for the consumer.

• numMsgsReceived : Number of messages received in the current interval
• numBytesReceived : Number of bytes received in the current interval
• numReceiveFailed : Number of messages failed to receive in the current interval
• numAcksSent : Number of acks sent in the current interval
• numAcksFailed : Number of acks failed to send in the current interval
• totalMsgsReceived : Total number of messages received
• totalBytesReceived : Total number of bytes received
• totalReceiveFailed : Total number of messages failed to receive
• totalAcksSent : Total number of acks sent
• totalAcksFailed : Total number of acks failed to sent

返回:

statistic for the consumer

close

void close()
    throws PulsarClientException

Close the consumer and stop the broker to push more messages.

指定者:

close 在接口中 AutoCloseable

指定者:

close 在接口中 Closeable

抛出:

PulsarClientException

closeAsync

CompletableFuture<Void> closeAsync()

Asynchronously close the consumer and stop the broker to push more messages

返回:

a future that can be used to track the completion of the operation

hasReachedEndOfTopic

boolean hasReachedEndOfTopic()

Return true if the topic was terminated and this consumer has already consumed all the messages in the topic. Please note that this does not simply mean that the consumer is caught up with the last message published by producers, rather the topic needs to be explicitly "terminated".

redeliverUnacknowledgedMessages

void redeliverUnacknowledgedMessages()

Redelivers all the unacknowledged messages. In Failover mode, the request is ignored if the consumer is not active for the given topic. In Shared mode, the consumers messages to be redelivered are distributed across all the connected consumers. This is a non blocking call and doesn't throw an exception. In case the connection breaks, the messages are redelivered after reconnect.

seek

void seek(MessageId messageId)
   throws PulsarClientException

Reset the subscription associated with this consumer to a specific message id.

The message id can either be a specific message or represent the first or last messages in the topic.

• MessageId.earliest : Reset the subscription on the earliest message available in the topic
• MessageId.latest : Reset the subscription on the latest message in the topic

Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

参数:

messageId - the message id where to reposition the subscription

抛出:

PulsarClientException

seek

void seek(long timestamp)
   throws PulsarClientException

Reset the subscription associated with this consumer to a specific message publish time. Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

参数:

timestamp - the message publish time where to reposition the subscription

抛出:

PulsarClientException

seekAsync

CompletableFuture<Void> seekAsync(MessageId messageId)

Reset the subscription associated with this consumer to a specific message id.

The message id can either be a specific message or represent the first or last messages in the topic.

• MessageId.earliest : Reset the subscription on the earliest message available in the topic
• MessageId.latest : Reset the subscription on the latest message in the topic

Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

参数:

messageId - the message id where to reposition the subscription

返回:

a future to track the completion of the seek operation

seekAsync

CompletableFuture<Void> seekAsync(long timestamp)

Reset the subscription associated with this consumer to a specific message publish time. Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

参数:

timestamp - the message publish time where to reposition the subscription

返回:

a future to track the completion of the seek operation

isConnected

boolean isConnected()

返回:

Whether the consumer is connected to the broker

getConsumerName

String getConsumerName()

Get the name of consumer.

返回:

consumer name.

pause

void pause()

Stop requesting new messages from the broker until resume() is called. Note that this might cause receive() to block until resume() is called and new messages are pushed by the broker.

resume

void resume()

Resume requesting messages from the broker.