diff --git a/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java b/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java index 1b2e5cc5a5e51..4b50f7e0c60b9 100644 --- a/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java +++ b/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java @@ -198,17 +198,21 @@ public interface ConsumerBuilder extends Cloneable { ConsumerBuilder ackTimeout(long ackTimeout, TimeUnit timeUnit); /** - * Acknowledgement returns receipt, but the message is not re-sent after getting receipt. + * Enables or disables the acknowledgment receipt feature. * - * Configure the acknowledgement timeout mechanism to redeliver the message if it is not acknowledged after - * ackTimeout, or to execute a timer task to check the acknowledgement timeout messages during every - * ackTimeoutTickTime period. + *

When this feature is enabled, the consumer ensures that acknowledgments are processed by the broker by + * waiting for a receipt from the broker. Even when the broker returns a receipt, it doesn't guarantee that the + * message won't be redelivered later due to certain implementation details. + * It is recommended to use the asynchronous {@link Consumer#acknowledgeAsync(Message)} method for acknowledgment + * when this feature is enabled. This is because using the synchronous {@link Consumer#acknowledge(Message)} method + * with acknowledgment receipt can cause performance issues due to the round trip to the server, which prevents + * pipelining (having multiple messages in-flight). With the asynchronous method, the consumer can continue + * consuming other messages while waiting for the acknowledgment receipts. * - * @param isAckReceiptEnabled {@link Boolean} enables acknowledgement for receipt + * @param isAckReceiptEnabled {@code true} to enable acknowledgment receipt, {@code false} to disable it * @return the consumer builder instance */ ConsumerBuilder isAckReceiptEnabled(boolean isAckReceiptEnabled); - /** * Define the granularity of the ack-timeout redelivery. *