You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by wa...@apache.org on 2022/07/08 21:21:00 UTC
[pulsar] branch master updated: [Doc] Describe default ack timeout and update grammar in ConsumerBuilder javadoc (#14084)
This is an automated email from the ASF dual-hosted git repository.
wave pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 86ab67f2246 [Doc] Describe default ack timeout and update grammar in ConsumerBuilder javadoc (#14084)
86ab67f2246 is described below
commit 86ab67f2246e99d4388177d30489199c3f25e2b8
Author: Libor Ryšavý <li...@users.noreply.github.com>
AuthorDate: Fri Jul 8 23:20:54 2022 +0200
[Doc] Describe default ack timeout and update grammar in ConsumerBuilder javadoc (#14084)
* [Doc] Describe default ack timeout in javadoc
* [Doc] Update javadoc grammar
Write in the simple present tense as much as possible if you are covering facts that were, are, and forever shall be true.
---
.../apache/pulsar/client/api/ConsumerBuilder.java | 109 +++++++++++----------
1 file changed, 55 insertions(+), 54 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 5e8970872b7..e303e55538e 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
@@ -80,11 +80,11 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Finalize the {@link Consumer} creation by subscribing to the topic.
*
- * <p>If the subscription does not exist, a new subscription will be created. By default the subscription
- * will be created at the end of the topic. See {@link #subscriptionInitialPosition(SubscriptionInitialPosition)}
+ * <p>If the subscription does not exist, a new subscription is created. By default, the subscription
+ * is created at the end of the topic. See {@link #subscriptionInitialPosition(SubscriptionInitialPosition)}
* to configure the initial position behavior.
*
- * <p>Once a subscription is created, it will retain the data and the subscription cursor even if the consumer
+ * <p>Once a subscription is created, it retains the data and the subscription cursor even if the consumer
* is not connected.
*
* @return the consumer builder instance
@@ -96,42 +96,42 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Finalize the {@link Consumer} creation by subscribing to the topic in asynchronous mode.
*
- * <p>If the subscription does not exist, a new subscription will be created. By default the subscription
- * will be created at the end of the topic. See {@link #subscriptionInitialPosition(SubscriptionInitialPosition)}
+ * <p>If the subscription does not exist, a new subscription is created. By default, the subscription
+ * is created at the end of the topic. See {@link #subscriptionInitialPosition(SubscriptionInitialPosition)}
* to configure the initial position behavior.
*
- * <p>Once a subscription is created, it will retain the data and the subscription cursor even
+ * <p>Once a subscription is created, it retains the data and the subscription cursor even
* if the consumer is not connected.
*
- * @return a future that will yield a {@link Consumer} instance
+ * @return a future that yields a {@link Consumer} instance
* @throws PulsarClientException
* if the the subscribe operation fails
*/
CompletableFuture<Consumer<T>> subscribeAsync();
/**
- * Specify the topics this consumer will subscribe on.
+ * Specify the topics this consumer subscribes on.
*
- * @param topicNames a set of topic that the consumer will subscribe on
+ * @param topicNames a set of topic that the consumer subscribes on
* @return the consumer builder instance
*/
ConsumerBuilder<T> topic(String... topicNames);
/**
- * Specify a list of topics that this consumer will subscribe on.
+ * Specify a list of topics that this consumer subscribes on.
*
- * @param topicNames a list of topic that the consumer will subscribe on
+ * @param topicNames a list of topic that the consumer subscribes on
* @return the consumer builder instance
*/
ConsumerBuilder<T> topics(List<String> topicNames);
/**
- * Specify a pattern for topics that this consumer will subscribe on.
+ * Specify a pattern for topics that this consumer subscribes on.
*
- * <p>The pattern will be applied to subscribe to all the topics, within a single namespace, that will match the
+ * <p>The pattern is applied to subscribe to all the topics, within a single namespace, that matches the
* pattern.
*
- * <p>The consumer will automatically subscribe to topics created after itself.
+ * <p>The consumer automatically subscribes to topics created after itself.
*
* @param topicsPattern
* a regular expression to select a list of topics to subscribe to
@@ -140,15 +140,15 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> topicsPattern(Pattern topicsPattern);
/**
- * Specify a pattern for topics that this consumer will subscribe on.
+ * Specify a pattern for topics that this consumer subscribes on.
*
- * <p>It accepts regular expression and will be compiled into a pattern internally. Eg.
+ * <p>It accepts regular expression that is compiled into a pattern internally. Eg.
* "persistent://public/default/pattern-topic-.*"
*
- * <p>The pattern will be applied to subscribe to all the topics, within a single namespace, that will match the
+ * <p>The pattern is applied to subscribe to all the topics, within a single namespace, that matches the
* pattern.
*
- * <p>The consumer will automatically subscribe to topics created after itself.
+ * <p>The consumer automatically subscribes to topics created after itself.
*
* @param topicsPattern
* given regular expression for topics pattern
@@ -169,7 +169,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Specify the subscription properties for this subscription.
- * Properties are immutable, and consumers under the same subscription will fail to create a subscription
+ * Properties are immutable, and consumers under the same subscription fails to create a subscription
* if they use different properties.
* @param subscriptionProperties
* @return
@@ -182,10 +182,11 @@ public interface ConsumerBuilder<T> extends Cloneable {
* 1 second.
*
* <p>By default, the acknowledge timeout is disabled and that means that messages delivered to a
- * consumer will not be re-delivered unless the consumer crashes.
+ * consumer is not re-delivered unless the consumer crashes. Since 2.3.0, when a dead letter policy
+ * is specified, and no ackTimeoutMillis is specified, the ack timeout is set to 30 seconds.
*
* <p>When enabling ack timeout, if a message is not acknowledged within the specified timeout
- * it will be re-delivered to the consumer (possibly to a different consumer in case of
+ * it is re-delivered to the consumer (possibly to a different consumer in case of
* a shared subscription).
*
* @param ackTimeout
@@ -197,7 +198,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> ackTimeout(long ackTimeout, TimeUnit timeUnit);
/**
- * Ack will return receipt but does not mean that the message will not be resent after get receipt.
+ * Ack returns receipt but does not mean that the message is not resent after get receipt.
*
* @param isAckReceiptEnabled {@link Boolean} is enable ack for receipt
* @return the consumer builder instance
@@ -207,8 +208,8 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Define the granularity of the ack-timeout redelivery.
*
- * <p>By default, the tick time is set to 1 second. Using an higher tick time will
- * reduce the memory overhead to track messages when the ack-timeout is set to
+ * <p>By default, the tick time is set to 1 second. Using an higher tick time
+ * reduces the memory overhead to track messages when the ack-timeout is set to
* bigger values (eg: 1hour).
*
* @param tickTime
@@ -223,7 +224,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Set the delay to wait before re-delivering messages that have failed to be process.
*
* <p>When application uses {@link Consumer#negativeAcknowledge(Message)}, the failed message
- * will be redelivered after a fixed timeout. The default is 1 min.
+ * is redelivered after a fixed timeout. The default is 1 min.
*
* @param redeliveryDelay
* redelivery delay for failed messages
@@ -268,8 +269,8 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Sets a {@link MessageListener} for the consumer
*
- * <p>When a {@link MessageListener} is set, application will receive messages through it. Calls to
- * {@link Consumer#receive()} will not be allowed.
+ * <p>When a {@link MessageListener} is set, application receives messages through it. Calls to
+ * {@link Consumer#receive()} is not allowed.
*
* @param messageListener
* the listener object
@@ -327,7 +328,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Sets the ConsumerCryptoFailureAction to the value specified.
*
* @param action
- * the action the consumer will take in case of decryption failures
+ * the action the consumer takes in case of decryption failures
* @return the consumer builder instance
*/
ConsumerBuilder<T> cryptoFailureAction(ConsumerCryptoFailureAction action);
@@ -347,8 +348,8 @@ public interface ConsumerBuilder<T> extends Cloneable {
* size is zero. {@link Consumer#receive()} function call should not be interrupted when the consumer queue size is
* zero.</li>
* <li>Doesn't support Batch-Message: if consumer receives any batch-message then it closes consumer connection with
- * broker and {@link Consumer#receive()} call will remain blocked while {@link Consumer#receiveAsync()} receives
- * exception in callback. <b> consumer will not be able receive any further message unless batch-message in pipeline
+ * broker and {@link Consumer#receive()} call remains blocked while {@link Consumer#receiveAsync()} receives
+ * exception in callback. <b> consumer is not able to receive any further message unless batch-message in pipeline
* is removed</b></li>
* </ul>
* Default value is {@code 1000} messages and should be good for most use cases.
@@ -362,10 +363,10 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Group the consumer acknowledgments for the specified time.
*
- * <p>By default, the consumer will use a 100 ms grouping time to send out the acknowledgments to the broker.
+ * <p>By default, the consumer uses a 100 ms grouping time to send out the acknowledgments to the broker.
*
- * <p>Setting a group time of 0, will send out the acknowledgments immediately. A longer ack group time
- * will be more efficient at the expense of a slight increase in message re-deliveries after a failure.
+ * <p>Setting a group time of 0 sends out the acknowledgments immediately. A longer ack group time
+ * is more efficient at the expense of a slight increase in message re-deliveries after a failure.
*
* @param delay
* the max amount of time an acknowledgemnt can be delayed
@@ -384,7 +385,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Set the max total receiver queue size across partitons.
*
- * <p>This setting will be used to reduce the receiver queue size for individual partitions
+ * <p>This setting is used to reduce the receiver queue size for individual partitions
* {@link #receiverQueueSize(int)} if the total exceeds this value (default: 50000).
* The purpose of this setting is to have an upper-limit on the number
* of messages that a consumer can be pushed at once from a broker, across all
@@ -420,14 +421,14 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> consumerEventListener(ConsumerEventListener consumerEventListener);
/**
- * If enabled, the consumer will read messages from the compacted topic rather than reading the full message backlog
+ * If enabled, the consumer reads messages from the compacted topic rather than reading the full message backlog
* of the topic. This means that, if the topic has been compacted, the consumer will only see the latest value for
* each key in the topic, up until the point in the topic message backlog that has been compacted. Beyond that
- * point, the messages will be sent as normal.
+ * point, the messages are sent as normal.
*
* <p>readCompacted can only be enabled subscriptions to persistent topics, which have a single active consumer
* (i.e. failure or exclusive subscriptions). Attempting to enable it on subscriptions to a non-persistent topics
- * or on a shared subscription, will lead to the subscription call throwing a PulsarClientException.
+ * or on a shared subscription leads to the subscription call throwing a PulsarClientException.
*
* @param readCompacted
* whether to read from the compacted topic
@@ -466,11 +467,11 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Sets priority level for the shared subscription consumers to which broker gives more priority while dispatching
* messages. Here, broker follows descending priorities. (eg: 0=max-priority, 1, 2,..)
*
- * <p>In Shared subscription mode, broker will first dispatch messages to max priority-level
- * consumers if they have permits, else broker will consider next priority level consumers.
+ * <p>In Shared subscription mode, broker first dispatches messages to max priority-level
+ * consumers if they have permits, else broker considers next priority level consumers.
*
* <p>If subscription has consumer-A with priorityLevel 0 and Consumer-B with priorityLevel 1
- * then broker will dispatch messages to only consumer-A until it runs out permit and then broker
+ * then broker dispatches messages to only consumer-A until it runs out permit and then broker
* starts dispatching messages to Consumer-B.
*
* <p><pre>
@@ -511,7 +512,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Set a name/value property with this consumer.
*
* <p>Properties are application defined metadata that can be attached to the consumer.
- * When getting the topic stats, this metadata will be associated to the consumer stats for easier identification.
+ * When getting the topic stats, this metadata are associated to the consumer stats for easier identification.
*
* @param key
* the property key
@@ -525,7 +526,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Add all the properties in the provided map to the consumer.
*
* <p>Properties are application defined metadata that can be attached to the consumer.
- * When getting the topic stats, this metadata will be associated to the consumer stats for easier identification.
+ * When getting the topic stats, this metadata are associated to the consumer stats for easier identification.
*
* @param properties the map with properties
* @return the consumer builder instance
@@ -560,9 +561,9 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Set dead letter policy for consumer.
*
- * <p>By default some message will redelivery so many times possible, even to the extent that it can be never stop.
- * By using dead letter mechanism messages will has the max redelivery count, when message exceeding the maximum
- * number of redeliveries, message will send to the Dead Letter Topic and acknowledged automatic.
+ * <p>By default, some message are redelivered so many times possible, even to the extent that it can be never stop.
+ * By using dead letter mechanism, messages have the max redelivery count. When message exceeds the maximum
+ * number of redeliveries, message is send to the Dead Letter Topic and acknowledged automatically.
*
* <p>You can enable the dead letter mechanism by setting dead letter policy.
* example:
@@ -583,12 +584,12 @@ public interface ConsumerBuilder<T> extends Cloneable {
* .subscribe();
* </pre>
* When a dead letter policy is specified, and no ackTimeoutMillis is specified,
- * then the ack timeout will be set to 30000 millisecond.
+ * then the ack timeout is set to 30000 millisecond.
*/
ConsumerBuilder<T> deadLetterPolicy(DeadLetterPolicy deadLetterPolicy);
/**
- * If enabled, the consumer will auto subscribe for partitions increasement.
+ * If enabled, the consumer auto-subscribes for partitions increasement.
* This is only for partitioned consumer.
*
* @param autoUpdate
@@ -643,7 +644,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
/**
* Set batch receive policy {@link BatchReceivePolicy} for consumer.
- * By default, consumer will use {@link BatchReceivePolicy#DEFAULT_POLICY} as batch receive policy.
+ * By default, consumer uses {@link BatchReceivePolicy#DEFAULT_POLICY} as batch receive policy.
*
* <p>Example:
* <pre>
@@ -657,8 +658,8 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> batchReceivePolicy(BatchReceivePolicy batchReceivePolicy);
/**
- * If enabled, the consumer will auto retry message.
- * default disabled.
+ * If enabled, the consumer auto retries message.
+ * Default: disabled.
*
* @param retryEnable
* whether to auto retry message
@@ -746,14 +747,14 @@ public interface ConsumerBuilder<T> extends Cloneable {
* Enable pooling of messages and the underlying data buffers.
* <p/>
* When pooling is enabled, the application is responsible for calling Message.release() after the handling of every
- * received message. If “release()” is not called on a received message, there will be a memory leak. If an
+ * received message. If “release()” is not called on a received message, it causes a memory leak. If an
* application attempts to use and already “released” message, it might experience undefined behavior (eg: memory
* corruption, deserialization error, etc.).
*/
ConsumerBuilder<T> poolMessages(boolean poolMessages);
/**
- * If it's configured with a non-null value, the consumer will use the processor to process the payload, including
+ * If it's configured with a non-null value, the consumer uses the processor to process the payload, including
* decoding it to messages and triggering the listener.
*
* Default: null
@@ -761,7 +762,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> messagePayloadProcessor(MessagePayloadProcessor payloadProcessor);
/**
- * Notice: the negativeAckRedeliveryBackoff will not work with `consumer.negativeAcknowledge(MessageId messageId)`
+ * Notice: the negativeAckRedeliveryBackoff doesn't work with `consumer.negativeAcknowledge(MessageId messageId)`
* because we are not able to get the redelivery count from the message ID.
*
* <p>Example:
@@ -775,7 +776,7 @@ public interface ConsumerBuilder<T> extends Cloneable {
ConsumerBuilder<T> negativeAckRedeliveryBackoff(RedeliveryBackoff negativeAckRedeliveryBackoff);
/**
- * Notice: the redeliveryBackoff will not work with `consumer.negativeAcknowledge(MessageId messageId)`
+ * Notice: the redeliveryBackoff doesn't work with `consumer.negativeAcknowledge(MessageId messageId)`
* because we are not able to get the redelivery count from the message ID.
*
* <p>Example: