(pulsar) 04/06: [fix][client] Fix the javadoc for ConsumerBuilder.isAckReceiptEnabled (#23452)

[lh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch branch-3.0
in repository https://gitbox.apache.org/repos/asf/pulsar.git

commit de9c06553b8ff600c6b67af5e1bebf3b8d8b03a5
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Mon Oct 14 13:19:19 2024 +0300

    [fix][client] Fix the javadoc for ConsumerBuilder.isAckReceiptEnabled (#23452)
    
    (cherry picked from commit e2fb0daac8411d76a3cca8df3e8f9f2b5c9b4ed6)
---
 .../org/apache/pulsar/client/api/ConsumerBuilder.java    | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

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 ff1a3cd73bb..eda5b1c41a9 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
@@ -200,17 +200,21 @@ public interface ConsumerBuilder<T> extends Cloneable {
     ConsumerBuilder<T> 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.
+     * <p>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<T> isAckReceiptEnabled(boolean isAckReceiptEnabled);
-
     /**
      * Define the granularity of the ack-timeout redelivery.
      *