From 48d4be6abeeebb53e888183b7bf8da300f437296 Mon Sep 17 00:00:00 2001 From: yangde Date: Wed, 30 Jun 2021 15:05:02 +0800 Subject: [PATCH 1/4] Add a call ACK / unack example to avoid confusing the retrial mechanism for beginners --- site2/docs/concepts-messaging.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md index d07d8f0e58cb7..2eff88eadf1df 100644 --- a/site2/docs/concepts-messaging.md +++ b/site2/docs/concepts-messaging.md @@ -48,7 +48,7 @@ A producer is a process that attaches to a topic and publishes messages to a Pul Producers send messages to brokers synchronously (sync) or asynchronously (async). -| Mode | Description | +| Mode | Description | |:-----------|-----------| | Sync send | The producer waits for an acknowledgement from the broker after sending every message. If the acknowledgment is not received, the producer treats the sending operation as a failure. | | Async send | The producer puts a message in a blocking queue and returns immediately. The client library sends the message to the broker in the background. If the queue is full (you can [configure](reference-configuration.md#broker) the maximum size), the producer is blocked or fails immediately when calling the API, depending on arguments passed to the producer. | @@ -149,6 +149,12 @@ Messages can be acknowledged in the following two ways: - Messages are acknowledged individually. With individual acknowledgement, the consumer needs to acknowledge each message and sends an acknowledgement request to the broker. - Messages are acknowledged cumulatively. With cumulative acknowledgement, the consumer only needs to acknowledge the last message it received. All messages in the stream up to (and including) the provided message are not re-delivered to that consumer. +The following example shows how to call the API : + +``` +consumer.acknowledge(msg); +``` + > **Note** > Cumulative acknowledgement cannot be used in the [shared subscription mode](#subscription-modes), because the shared subscription mode involves multiple consumers who have access to the same subscription. In the shared subscription mode, messages are acknowledged individually. @@ -164,6 +170,12 @@ In the shared and Key_Shared subscription modes, you can negatively acknowledge Be aware that negative acknowledgment on ordered subscription types, such as Exclusive, Failover and Key_Shared, can cause failed messages to arrive consumers out of the original order. +The following example shows how to call the API : + +``` +consumer.negativeAcknowledge(msg); +``` + > **Note** > If batching is enabled, other messages and the negatively acknowledged messages in the same batch are redelivered to the consumer. @@ -198,7 +210,7 @@ The default dead letter topic uses this format: ``` --DLQ ``` - + If you want to specify the name of the dead letter topic, use this Java client example: ```java @@ -213,7 +225,7 @@ Consumer consumer = pulsarClient.newConsumer(Schema.BYTES) .subscribe(); ``` - + Dead letter topic depends on message re-delivery. Messages are redelivered either due to [acknowledgement timeout](#acknowledgement-timeout) or [negative acknowledgement](#negative-acknowledgement). If you are going to use negative acknowledgement on a message, make sure it is negatively acknowledged before the acknowledgement timeout. > **Note** @@ -242,6 +254,14 @@ Consumer consumer = pulsarClient.newConsumer(Schema.BYTES) .subscribe(); ``` +The following example shows how to call the API to put messages into the retrial queue: + +``` +consumer.reconsumeLater(msg,3,TimeUnit.SECONDS); +``` + + + ## Topics As in other pub-sub systems, topics in Pulsar are named channels for transmitting messages from producers to consumers. Topic names are URLs that have a well-defined structure: From 8d12f5462e94cf764abe4cf68f541535884176ea Mon Sep 17 00:00:00 2001 From: yangde Date: Wed, 30 Jun 2021 18:47:54 +0800 Subject: [PATCH 2/4] apply the change to other code snippets to mark the code block as Java language for correct highlight --- site2/docs/concepts-messaging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md index 2eff88eadf1df..32be68cef8e98 100644 --- a/site2/docs/concepts-messaging.md +++ b/site2/docs/concepts-messaging.md @@ -151,7 +151,7 @@ Messages can be acknowledged in the following two ways: The following example shows how to call the API : -``` +```java consumer.acknowledge(msg); ``` @@ -172,7 +172,7 @@ Be aware that negative acknowledgment on ordered subscription types, such as Exc The following example shows how to call the API : -``` +```java consumer.negativeAcknowledge(msg); ``` @@ -256,7 +256,7 @@ Consumer consumer = pulsarClient.newConsumer(Schema.BYTES) The following example shows how to call the API to put messages into the retrial queue: -``` +```java consumer.reconsumeLater(msg,3,TimeUnit.SECONDS); ``` From 0f70df85028f79da226ceea5cd33334410cee746 Mon Sep 17 00:00:00 2001 From: yangde Date: Thu, 1 Jul 2021 09:54:49 +0800 Subject: [PATCH 3/4] add an example for cumulative acknowledgement --- site2/docs/concepts-messaging.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md index 32be68cef8e98..5fd9161e99e82 100644 --- a/site2/docs/concepts-messaging.md +++ b/site2/docs/concepts-messaging.md @@ -149,11 +149,16 @@ Messages can be acknowledged in the following two ways: - Messages are acknowledged individually. With individual acknowledgement, the consumer needs to acknowledge each message and sends an acknowledgement request to the broker. - Messages are acknowledged cumulatively. With cumulative acknowledgement, the consumer only needs to acknowledge the last message it received. All messages in the stream up to (and including) the provided message are not re-delivered to that consumer. -The following example shows how to call the API : +The following example shows how to call the API With individual acknowledgement: ```java consumer.acknowledge(msg); ``` +If you are going to acknowledge messages cumulatively, you can use the following API: +```java +consumer.acknowledgeCumulative(msg); +``` + > **Note** > Cumulative acknowledgement cannot be used in the [shared subscription mode](#subscription-modes), because the shared subscription mode involves multiple consumers who have access to the same subscription. In the shared subscription mode, messages are acknowledged individually. @@ -173,6 +178,7 @@ Be aware that negative acknowledgment on ordered subscription types, such as Exc The following example shows how to call the API : ```java +//With calling this api, messages are negatively acknowledged consumer.negativeAcknowledge(msg); ``` From 6b83fcef8fd4666cb3aea860478d5a7ec233fd99 Mon Sep 17 00:00:00 2001 From: yangde Date: Thu, 1 Jul 2021 11:09:08 +0800 Subject: [PATCH 4/4] Pls keep consistent overall --- site2/docs/concepts-messaging.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md index 5fd9161e99e82..573be02432789 100644 --- a/site2/docs/concepts-messaging.md +++ b/site2/docs/concepts-messaging.md @@ -149,12 +149,12 @@ Messages can be acknowledged in the following two ways: - Messages are acknowledged individually. With individual acknowledgement, the consumer needs to acknowledge each message and sends an acknowledgement request to the broker. - Messages are acknowledged cumulatively. With cumulative acknowledgement, the consumer only needs to acknowledge the last message it received. All messages in the stream up to (and including) the provided message are not re-delivered to that consumer. -The following example shows how to call the API With individual acknowledgement: +If you want to acknowledge messages individually, you can use the following API. ```java consumer.acknowledge(msg); ``` -If you are going to acknowledge messages cumulatively, you can use the following API: +If you want to acknowledge messages cumulatively, you can use the following API. ```java consumer.acknowledgeCumulative(msg); ``` @@ -175,7 +175,7 @@ In the shared and Key_Shared subscription modes, you can negatively acknowledge Be aware that negative acknowledgment on ordered subscription types, such as Exclusive, Failover and Key_Shared, can cause failed messages to arrive consumers out of the original order. -The following example shows how to call the API : +If you want to acknowledge messages negatively, you can use the following API. ```java //With calling this api, messages are negatively acknowledged @@ -260,7 +260,7 @@ Consumer consumer = pulsarClient.newConsumer(Schema.BYTES) .subscribe(); ``` -The following example shows how to call the API to put messages into the retrial queue: +If you want to put messages into a retrial queue, you can use the following API. ```java consumer.reconsumeLater(msg,3,TimeUnit.SECONDS);