You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ur...@apache.org on 2022/03/17 06:03:43 UTC
[pulsar-site] branch main updated: Docs sync done from apache/pulsar(#828d057)
This is an automated email from the ASF dual-hosted git repository.
urfree pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 70f9061 Docs sync done from apache/pulsar(#828d057)
70f9061 is described below
commit 70f9061cc79bc0d039753f24f49ecb65ad3d734c
Author: Pulsar Site Updater <de...@pulsar.apache.org>
AuthorDate: Thu Mar 17 06:02:19 2022 +0000
Docs sync done from apache/pulsar(#828d057)
---
site2/docs/assets/retry-letter-topic.svg | 1 +
site2/docs/concepts-messaging.md | 184 +++++++++++--------
site2/website-next/docs/concepts-messaging.md | 201 +++++++++++++--------
.../static/assets/retry-letter-topic.svg | 1 +
.../version-2.2.0/concepts-messaging.md | 201 +++++++++++++--------
.../version-2.2.1/concepts-messaging.md | 201 +++++++++++++--------
6 files changed, 483 insertions(+), 306 deletions(-)
diff --git a/site2/docs/assets/retry-letter-topic.svg b/site2/docs/assets/retry-letter-topic.svg
new file mode 100644
index 0000000..16951c2
--- /dev/null
+++ b/site2/docs/assets/retry-letter-topic.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="959" height="420"><g transform="translate(-620 -340.00000000000006)" lucid:page-tab-id="0_0"><path d="M0 0h1870.87v1322.83H0z" fill="#fff"/><path d="M640 540c0-3.3 2.7-6 6-6h128c3.3 0 6 2.7 6 6v48c0 3.3-2.7 6-6 6H646c-3.3 0-6-2.7-6-6z" stroke="#474e55" stroke-width="3" fill="#fff"/><use xlink:href="#a" transform="matrix(1,0,0,1,645,539) translate(16.458767361111114 31.27072482638 [...]
\ No newline at end of file
diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md
index 595000f..9726249 100644
--- a/site2/docs/concepts-messaging.md
+++ b/site2/docs/concepts-messaging.md
@@ -190,6 +190,8 @@ In Shared and Key_Shared subscription types, consumers can negatively acknowledg
Be aware that negative acknowledgments on ordered subscription types, such as Exclusive, Failover and Key_Shared, might cause failed messages being sent to consumers out of the original order.
+If you are going to use negative acknowledgment on a message, make sure it is negatively acknowledged before the acknowledgment timeout.
+
Use the following API to negatively acknowledge message consumption.
```java
@@ -209,23 +211,34 @@ message = consumer.receive();
consumer.acknowledge(message);
```
-> **Note**
-> If batching is enabled, all messages in one batch are redelivered to the consumer.
-
-### Negative redelivery backoff
-
-It happens sometimes that consumers fail to process messages successfully. In this case, you can use [negative acknowledgement](#negative-acknowledgement) to redeliver the messages after consumption failures. For the Shared subscription type, the messages are redelivered to other consumers; for other subscription types, the messages are redelivered to the same consumer.
-
-But this is not flexible enough. A better way is to use the **redelivery backoff mechanism**. You can redeliver messages with different delays by setting the number of times the messages are retried.
-
+To redeliver messages with different delays, you can use the **redelivery backoff mechanism** by setting the number of retries to deliver the messages.
Use the following API to enable `Negative Redelivery Backoff`.
```java
-consumer.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
- .minDelayMs(1000)
- .maxDelayMs(60 * 1000)
- .build())
+Consumer<byte[]> consumer = pulsarClient.newConsumer()
+ .topic(topic)
+ .subscriptionName("sub-negative-ack")
+ .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
+ .minDelayMs(1000)
+ .maxDelayMs(60 * 1000)
+ .build())
+ .subscribe();
```
+The message redelivery behavior should be as follows.
+
+Redelivery count | Redelivery delay
+:--------------------|:-----------
+1 | 10 + 1 seconds
+2 | 10 + 2 seconds
+3 | 10 + 4 seconds
+4 | 10 + 8 seconds
+5 | 10 + 16 seconds
+6 | 10 + 32 seconds
+7 | 10 + 60 seconds
+8 | 10 + 60 seconds
+> **Note**
+> If batching is enabled, all messages in one batch are redelivered to the consumer.
### Acknowledgement timeout
@@ -280,6 +293,82 @@ message = consumer.receive();
consumer.acknowledge(message);
```
+### Retry letter topic
+
+The retry letter topic allows you to store the messages that failed to be consumed and retry consuming them later. With this method, you can customize the interval at which the messages are redelivered. Consumers on the original topic are automatically subscribed to the retry letter topic as well. Once the maximum number of retries has been reached, the unconsumed messages are moved to a [dead letter topic](#dead-letter-topic) for manual processing.
+
+The diagram below illustrates the concept of the retry letter topic.
+
+
+The intention of using retry letter topic is different from using [delayed message delivery](#delayed-message-delivery), even though both are aiming to consume a message later. Retry letter topic serves failure handling through message redelivery to ensure critical data is not lost, while delayed message delivery is intended to deliver a message with a specified time of delay.
+
+By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+
+Use the following API to consume messages from a retry letter topic. When the value of `maxRedeliverCount` is reached, the unconsumed messages are moved to a dead letter topic.
+
+```java
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
+ .subscribe();
+```
+The default retry letter topic uses this format:
+```
+<topicname>-<subscriptionname>-RETRY
+```
+Use the Java client to specify the name of the retry letter topic.
+```java
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .retryLetterTopic("my-retry-letter-topic-name")
+ .build())
+ .subscribe();
+```
+
+The messages in the retry letter topic contain some special properties that are automatically created by the client.
+
+Special property | Description
+:--------------------|:-----------
+`REAL_TOPIC` | The real topic name.
+`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
+`RECONSUMETIMES` | The number of retries to consume messages.
+`DELAY_TIME` | Message retry interval in milliseconds.
+**Example**
+```
+REAL_TOPIC = persistent://public/default/my-topic
+ORIGIN_MESSAGE_ID = 1:0:-1:0
+RECONSUMETIMES = 6
+DELAY_TIME = 3000
+```
+
+Use the following API to store the messages in a retrial queue.
+
+```java
+consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
+```
+
+Use the following API to add custom properties for the `reconsumeLater` function. In the next attempt to consume, custom properties can be get from message#getProperty.
+
+```java
+Map<String, String> customProperties = new HashMap<String, String>();
+customProperties.put("custom-key-1", "custom-value-1");
+customProperties.put("custom-key-2", "custom-value-2");
+consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+```
+> **Note**
+> * Currently, retry letter topic is enabled in Shared subscription types.
+> * Compared with negative acknowledgment, retry letter topic is more suitable for messages that require a large number of retries with a configurable retry interval. Because messages in the retry letter topic are persisted to BookKeeper, while messages that need to be retried due to negative acknowledgment are cached on the client side.
+
### Dead letter topic
Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
@@ -288,7 +377,7 @@ Enable dead letter topic in a Java client using the default dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.deadLetterPolicy(DeadLetterPolicy.builder()
@@ -306,12 +395,12 @@ Use the Java client to specify the name of the dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.deadLetterPolicy(DeadLetterPolicy.builder()
.maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
+ .deadLetterTopic("my-dead-letter-topic-name")
.build())
.subscribe();
@@ -321,76 +410,21 @@ By default, there is no subscription during a DLQ topic creation. Without a just
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
.deadLetterPolicy(DeadLetterPolicy.builder()
.maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
+ .deadLetterTopic("my-dead-letter-topic-name")
.initialSubscriptionName("init-sub")
.build())
.subscribe();
```
-Dead letter topic depends on message redelivery. 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.
-
+Dead letter topic serves message redelivery, which is triggered by [acknowledgement timeout](#acknowledgement-timeout) or [negative acknowledgement](#negative-acknowledgement) or [retry letter topic](#retry-letter-topic) .
> **Note**
-> Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
-
-### Retry letter topic
-
-For many online business systems, a message is re-consumed when exception occurs in the business logic processing. To configure the delay time for re-consuming the failed messages, you can configure the producer to send messages to both the business topic and the retry letter topic, and enable automatic retry on the consumer. With this setting, the messages that are not consumed will be stored in the retry letter topic. After the specified delay time, the consumer automatically consumes [...]
-
-By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
-
-Use the following API to consume messages from a retry letter topic.
-
-```java
-Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .enableRetry(true)
- .receiverQueueSize(100)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .retryLetterTopic("persistent://my-property/my-ns/my-subscription-custom-Retry")
- .build())
- .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
- .subscribe();
-```
-
-The messages in the retry letter topic contain some special properties that are automatically created by the client.
-
-Special property | Description
-:--------------------|:-----------
-`REAL_TOPIC` | The real topic name.
-`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
-`RECONSUMETIMES` | The retry consume times.
-`DELAY_TIME` | Message delay timeMs.
-**Example**
-```
-REAL_TOPIC = persistent://public/default/my-topic
-ORIGIN_MESSAGE_ID = 1:0:-1:0
-RECONSUMETIMES = 6
-DELAY_TIME = 3000
-```
-
-Use the following API to store the messages in a retrial queue.
-
-```java
-consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
-```
-
-Use the following API to add custom properties for the `reconsumeLater` function.
-
-```java
-Map<String, String> customProperties = new HashMap<String, String>();
-customProperties.put("custom-key-1", "custom-value-1");
-customProperties.put("custom-key-2", "custom-value-2");
-consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
-```
+> * Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
## Topics
diff --git a/site2/website-next/docs/concepts-messaging.md b/site2/website-next/docs/concepts-messaging.md
index c370181..8f542db 100644
--- a/site2/website-next/docs/concepts-messaging.md
+++ b/site2/website-next/docs/concepts-messaging.md
@@ -216,6 +216,8 @@ In Shared and Key_Shared subscription types, consumers can negatively acknowledg
Be aware that negative acknowledgments on ordered subscription types, such as Exclusive, Failover and Key_Shared, might cause failed messages being sent to consumers out of the original order.
+If you are going to use negative acknowledgment on a message, make sure it is negatively acknowledged before the acknowledgment timeout.
+
Use the following API to negatively acknowledge message consumption.
```java
@@ -237,28 +239,40 @@ consumer.acknowledge(message);
```
-:::note
-
-If batching is enabled, all messages in one batch are redelivered to the consumer.
-
-:::
+To redeliver messages with different delays, you can use the **redelivery backoff mechanism** by setting the number of retries to deliver the messages.
+Use the following API to enable `Negative Redelivery Backoff`.
-### Negative redelivery backoff
+```java
-It happens sometimes that consumers fail to process messages successfully. In this case, you can use [negative acknowledgement](#negative-acknowledgement) to redeliver the messages after consumption failures. For the Shared subscription type, the messages are redelivered to other consumers; for other subscription types, the messages are redelivered to the same consumer.
+Consumer<byte[]> consumer = pulsarClient.newConsumer()
+ .topic(topic)
+ .subscriptionName("sub-negative-ack")
+ .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
+ .minDelayMs(1000)
+ .maxDelayMs(60 * 1000)
+ .build())
+ .subscribe();
-But this is not flexible enough. A better way is to use the **redelivery backoff mechanism**. You can redeliver messages with different delays by setting the number of times the messages are retried.
+```
-Use the following API to enable `Negative Redelivery Backoff`.
+The message redelivery behavior should be as follows.
-```java
+Redelivery count | Redelivery delay
+:--------------------|:-----------
+1 | 10 + 1 seconds
+2 | 10 + 2 seconds
+3 | 10 + 4 seconds
+4 | 10 + 8 seconds
+5 | 10 + 16 seconds
+6 | 10 + 32 seconds
+7 | 10 + 60 seconds
+8 | 10 + 60 seconds
+:::note
-consumer.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
- .minDelayMs(1000)
- .maxDelayMs(60 * 1000)
- .build())
+If batching is enabled, all messages in one batch are redelivered to the consumer.
-```
+:::
### Acknowledgement timeout
@@ -321,137 +335,170 @@ consumer.acknowledge(message);
```
-### Dead letter topic
+### Retry letter topic
-Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
+The retry letter topic allows you to store the messages that failed to be consumed and retry consuming them later. With this method, you can customize the interval at which the messages are redelivered. Consumers on the original topic are automatically subscribed to the retry letter topic as well. Once the maximum number of retries has been reached, the unconsumed messages are moved to a [dead letter topic](#dead-letter-topic) for manual processing.
-Enable dead letter topic in a Java client using the default dead letter topic.
+The diagram below illustrates the concept of the retry letter topic.
+
+
+The intention of using retry letter topic is different from using [delayed message delivery](#delayed-message-delivery), even though both are aiming to consume a message later. Retry letter topic serves failure handling through message redelivery to ensure critical data is not lost, while delayed message delivery is intended to deliver a message with a specified time of delay.
+
+By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+
+Use the following API to consume messages from a retry letter topic. When the value of `maxRedeliverCount` is reached, the unconsumed messages are moved to a dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .build())
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The default dead letter topic uses this format:
+The default retry letter topic uses this format:
```
-<topicname>-<subscriptionname>-DLQ
+<topicname>-<subscriptionname>-RETRY
```
-Use the Java client to specify the name of the dead letter topic.
+Use the Java client to specify the name of the retry letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .build())
- .subscribe();
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .retryLetterTopic("my-retry-letter-topic-name")
+ .build())
+ .subscribe();
```
-By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
+The messages in the retry letter topic contain some special properties that are automatically created by the client.
+
+Special property | Description
+:--------------------|:-----------
+`REAL_TOPIC` | The real topic name.
+`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
+`RECONSUMETIMES` | The number of retries to consume messages.
+`DELAY_TIME` | Message retry interval in milliseconds.
+**Example**
+
+```
+
+REAL_TOPIC = persistent://public/default/my-topic
+ORIGIN_MESSAGE_ID = 1:0:-1:0
+RECONSUMETIMES = 6
+DELAY_TIME = 3000
+
+```
+
+Use the following API to store the messages in a retrial queue.
```java
-Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .initialSubscriptionName("init-sub")
- .build())
- .subscribe();
+consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
```
-Dead letter topic depends on message redelivery. 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.
+Use the following API to add custom properties for the `reconsumeLater` function. In the next attempt to consume, custom properties can be get from message#getProperty.
+
+```java
+
+Map<String, String> customProperties = new HashMap<String, String>();
+customProperties.put("custom-key-1", "custom-value-1");
+customProperties.put("custom-key-2", "custom-value-2");
+consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+
+```
:::note
-Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+* Currently, retry letter topic is enabled in Shared subscription types.
+* Compared with negative acknowledgment, retry letter topic is more suitable for messages that require a large number of retries with a configurable retry interval. Because messages in the retry letter topic are persisted to BookKeeper, while messages that need to be retried due to negative acknowledgment are cached on the client side.
:::
-### Retry letter topic
-
-For many online business systems, a message is re-consumed when exception occurs in the business logic processing. To configure the delay time for re-consuming the failed messages, you can configure the producer to send messages to both the business topic and the retry letter topic, and enable automatic retry on the consumer. With this setting, the messages that are not consumed will be stored in the retry letter topic. After the specified delay time, the consumer automatically consumes [...]
+### Dead letter topic
-By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
-Use the following API to consume messages from a retry letter topic.
+Enable dead letter topic in a Java client using the default dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
- .enableRetry(true)
- .receiverQueueSize(100)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .retryLetterTopic("persistent://my-property/my-ns/my-subscription-custom-Retry")
- .build())
- .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The messages in the retry letter topic contain some special properties that are automatically created by the client.
-
-Special property | Description
-:--------------------|:-----------
-`REAL_TOPIC` | The real topic name.
-`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
-`RECONSUMETIMES` | The retry consume times.
-`DELAY_TIME` | Message delay timeMs.
-**Example**
+The default dead letter topic uses this format:
```
-REAL_TOPIC = persistent://public/default/my-topic
-ORIGIN_MESSAGE_ID = 1:0:-1:0
-RECONSUMETIMES = 6
-DELAY_TIME = 3000
+<topicname>-<subscriptionname>-DLQ
```
-Use the following API to store the messages in a retrial queue.
+Use the Java client to specify the name of the dead letter topic.
```java
-consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .build())
+ .subscribe();
```
-Use the following API to add custom properties for the `reconsumeLater` function.
+By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
```java
-Map<String, String> customProperties = new HashMap<String, String>();
-customProperties.put("custom-key-1", "custom-value-1");
-customProperties.put("custom-key-2", "custom-value-2");
-consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .initialSubscriptionName("init-sub")
+ .build())
+ .subscribe();
```
+Dead letter topic serves message redelivery, which is triggered by [acknowledgement timeout](#acknowledgement-timeout) or [negative acknowledgement](#negative-acknowledgement) or [retry letter topic](#retry-letter-topic) .
+:::note
+
+* Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+
+:::
+
## 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:
diff --git a/site2/website-next/static/assets/retry-letter-topic.svg b/site2/website-next/static/assets/retry-letter-topic.svg
new file mode 100644
index 0000000..16951c2
--- /dev/null
+++ b/site2/website-next/static/assets/retry-letter-topic.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:lucid="lucid" width="959" height="420"><g transform="translate(-620 -340.00000000000006)" lucid:page-tab-id="0_0"><path d="M0 0h1870.87v1322.83H0z" fill="#fff"/><path d="M640 540c0-3.3 2.7-6 6-6h128c3.3 0 6 2.7 6 6v48c0 3.3-2.7 6-6 6H646c-3.3 0-6-2.7-6-6z" stroke="#474e55" stroke-width="3" fill="#fff"/><use xlink:href="#a" transform="matrix(1,0,0,1,645,539) translate(16.458767361111114 31.27072482638 [...]
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.2.0/concepts-messaging.md b/site2/website-next/versioned_docs/version-2.2.0/concepts-messaging.md
index c370181..8f542db 100644
--- a/site2/website-next/versioned_docs/version-2.2.0/concepts-messaging.md
+++ b/site2/website-next/versioned_docs/version-2.2.0/concepts-messaging.md
@@ -216,6 +216,8 @@ In Shared and Key_Shared subscription types, consumers can negatively acknowledg
Be aware that negative acknowledgments on ordered subscription types, such as Exclusive, Failover and Key_Shared, might cause failed messages being sent to consumers out of the original order.
+If you are going to use negative acknowledgment on a message, make sure it is negatively acknowledged before the acknowledgment timeout.
+
Use the following API to negatively acknowledge message consumption.
```java
@@ -237,28 +239,40 @@ consumer.acknowledge(message);
```
-:::note
-
-If batching is enabled, all messages in one batch are redelivered to the consumer.
-
-:::
+To redeliver messages with different delays, you can use the **redelivery backoff mechanism** by setting the number of retries to deliver the messages.
+Use the following API to enable `Negative Redelivery Backoff`.
-### Negative redelivery backoff
+```java
-It happens sometimes that consumers fail to process messages successfully. In this case, you can use [negative acknowledgement](#negative-acknowledgement) to redeliver the messages after consumption failures. For the Shared subscription type, the messages are redelivered to other consumers; for other subscription types, the messages are redelivered to the same consumer.
+Consumer<byte[]> consumer = pulsarClient.newConsumer()
+ .topic(topic)
+ .subscriptionName("sub-negative-ack")
+ .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
+ .minDelayMs(1000)
+ .maxDelayMs(60 * 1000)
+ .build())
+ .subscribe();
-But this is not flexible enough. A better way is to use the **redelivery backoff mechanism**. You can redeliver messages with different delays by setting the number of times the messages are retried.
+```
-Use the following API to enable `Negative Redelivery Backoff`.
+The message redelivery behavior should be as follows.
-```java
+Redelivery count | Redelivery delay
+:--------------------|:-----------
+1 | 10 + 1 seconds
+2 | 10 + 2 seconds
+3 | 10 + 4 seconds
+4 | 10 + 8 seconds
+5 | 10 + 16 seconds
+6 | 10 + 32 seconds
+7 | 10 + 60 seconds
+8 | 10 + 60 seconds
+:::note
-consumer.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
- .minDelayMs(1000)
- .maxDelayMs(60 * 1000)
- .build())
+If batching is enabled, all messages in one batch are redelivered to the consumer.
-```
+:::
### Acknowledgement timeout
@@ -321,137 +335,170 @@ consumer.acknowledge(message);
```
-### Dead letter topic
+### Retry letter topic
-Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
+The retry letter topic allows you to store the messages that failed to be consumed and retry consuming them later. With this method, you can customize the interval at which the messages are redelivered. Consumers on the original topic are automatically subscribed to the retry letter topic as well. Once the maximum number of retries has been reached, the unconsumed messages are moved to a [dead letter topic](#dead-letter-topic) for manual processing.
-Enable dead letter topic in a Java client using the default dead letter topic.
+The diagram below illustrates the concept of the retry letter topic.
+
+
+The intention of using retry letter topic is different from using [delayed message delivery](#delayed-message-delivery), even though both are aiming to consume a message later. Retry letter topic serves failure handling through message redelivery to ensure critical data is not lost, while delayed message delivery is intended to deliver a message with a specified time of delay.
+
+By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+
+Use the following API to consume messages from a retry letter topic. When the value of `maxRedeliverCount` is reached, the unconsumed messages are moved to a dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .build())
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The default dead letter topic uses this format:
+The default retry letter topic uses this format:
```
-<topicname>-<subscriptionname>-DLQ
+<topicname>-<subscriptionname>-RETRY
```
-Use the Java client to specify the name of the dead letter topic.
+Use the Java client to specify the name of the retry letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .build())
- .subscribe();
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .retryLetterTopic("my-retry-letter-topic-name")
+ .build())
+ .subscribe();
```
-By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
+The messages in the retry letter topic contain some special properties that are automatically created by the client.
+
+Special property | Description
+:--------------------|:-----------
+`REAL_TOPIC` | The real topic name.
+`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
+`RECONSUMETIMES` | The number of retries to consume messages.
+`DELAY_TIME` | Message retry interval in milliseconds.
+**Example**
+
+```
+
+REAL_TOPIC = persistent://public/default/my-topic
+ORIGIN_MESSAGE_ID = 1:0:-1:0
+RECONSUMETIMES = 6
+DELAY_TIME = 3000
+
+```
+
+Use the following API to store the messages in a retrial queue.
```java
-Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .initialSubscriptionName("init-sub")
- .build())
- .subscribe();
+consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
```
-Dead letter topic depends on message redelivery. 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.
+Use the following API to add custom properties for the `reconsumeLater` function. In the next attempt to consume, custom properties can be get from message#getProperty.
+
+```java
+
+Map<String, String> customProperties = new HashMap<String, String>();
+customProperties.put("custom-key-1", "custom-value-1");
+customProperties.put("custom-key-2", "custom-value-2");
+consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+
+```
:::note
-Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+* Currently, retry letter topic is enabled in Shared subscription types.
+* Compared with negative acknowledgment, retry letter topic is more suitable for messages that require a large number of retries with a configurable retry interval. Because messages in the retry letter topic are persisted to BookKeeper, while messages that need to be retried due to negative acknowledgment are cached on the client side.
:::
-### Retry letter topic
-
-For many online business systems, a message is re-consumed when exception occurs in the business logic processing. To configure the delay time for re-consuming the failed messages, you can configure the producer to send messages to both the business topic and the retry letter topic, and enable automatic retry on the consumer. With this setting, the messages that are not consumed will be stored in the retry letter topic. After the specified delay time, the consumer automatically consumes [...]
+### Dead letter topic
-By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
-Use the following API to consume messages from a retry letter topic.
+Enable dead letter topic in a Java client using the default dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
- .enableRetry(true)
- .receiverQueueSize(100)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .retryLetterTopic("persistent://my-property/my-ns/my-subscription-custom-Retry")
- .build())
- .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The messages in the retry letter topic contain some special properties that are automatically created by the client.
-
-Special property | Description
-:--------------------|:-----------
-`REAL_TOPIC` | The real topic name.
-`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
-`RECONSUMETIMES` | The retry consume times.
-`DELAY_TIME` | Message delay timeMs.
-**Example**
+The default dead letter topic uses this format:
```
-REAL_TOPIC = persistent://public/default/my-topic
-ORIGIN_MESSAGE_ID = 1:0:-1:0
-RECONSUMETIMES = 6
-DELAY_TIME = 3000
+<topicname>-<subscriptionname>-DLQ
```
-Use the following API to store the messages in a retrial queue.
+Use the Java client to specify the name of the dead letter topic.
```java
-consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .build())
+ .subscribe();
```
-Use the following API to add custom properties for the `reconsumeLater` function.
+By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
```java
-Map<String, String> customProperties = new HashMap<String, String>();
-customProperties.put("custom-key-1", "custom-value-1");
-customProperties.put("custom-key-2", "custom-value-2");
-consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .initialSubscriptionName("init-sub")
+ .build())
+ .subscribe();
```
+Dead letter topic serves message redelivery, which is triggered by [acknowledgement timeout](#acknowledgement-timeout) or [negative acknowledgement](#negative-acknowledgement) or [retry letter topic](#retry-letter-topic) .
+:::note
+
+* Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+
+:::
+
## 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:
diff --git a/site2/website-next/versioned_docs/version-2.2.1/concepts-messaging.md b/site2/website-next/versioned_docs/version-2.2.1/concepts-messaging.md
index c370181..8f542db 100644
--- a/site2/website-next/versioned_docs/version-2.2.1/concepts-messaging.md
+++ b/site2/website-next/versioned_docs/version-2.2.1/concepts-messaging.md
@@ -216,6 +216,8 @@ In Shared and Key_Shared subscription types, consumers can negatively acknowledg
Be aware that negative acknowledgments on ordered subscription types, such as Exclusive, Failover and Key_Shared, might cause failed messages being sent to consumers out of the original order.
+If you are going to use negative acknowledgment on a message, make sure it is negatively acknowledged before the acknowledgment timeout.
+
Use the following API to negatively acknowledge message consumption.
```java
@@ -237,28 +239,40 @@ consumer.acknowledge(message);
```
-:::note
-
-If batching is enabled, all messages in one batch are redelivered to the consumer.
-
-:::
+To redeliver messages with different delays, you can use the **redelivery backoff mechanism** by setting the number of retries to deliver the messages.
+Use the following API to enable `Negative Redelivery Backoff`.
-### Negative redelivery backoff
+```java
-It happens sometimes that consumers fail to process messages successfully. In this case, you can use [negative acknowledgement](#negative-acknowledgement) to redeliver the messages after consumption failures. For the Shared subscription type, the messages are redelivered to other consumers; for other subscription types, the messages are redelivered to the same consumer.
+Consumer<byte[]> consumer = pulsarClient.newConsumer()
+ .topic(topic)
+ .subscriptionName("sub-negative-ack")
+ .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
+ .minDelayMs(1000)
+ .maxDelayMs(60 * 1000)
+ .build())
+ .subscribe();
-But this is not flexible enough. A better way is to use the **redelivery backoff mechanism**. You can redeliver messages with different delays by setting the number of times the messages are retried.
+```
-Use the following API to enable `Negative Redelivery Backoff`.
+The message redelivery behavior should be as follows.
-```java
+Redelivery count | Redelivery delay
+:--------------------|:-----------
+1 | 10 + 1 seconds
+2 | 10 + 2 seconds
+3 | 10 + 4 seconds
+4 | 10 + 8 seconds
+5 | 10 + 16 seconds
+6 | 10 + 32 seconds
+7 | 10 + 60 seconds
+8 | 10 + 60 seconds
+:::note
-consumer.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
- .minDelayMs(1000)
- .maxDelayMs(60 * 1000)
- .build())
+If batching is enabled, all messages in one batch are redelivered to the consumer.
-```
+:::
### Acknowledgement timeout
@@ -321,137 +335,170 @@ consumer.acknowledge(message);
```
-### Dead letter topic
+### Retry letter topic
-Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
+The retry letter topic allows you to store the messages that failed to be consumed and retry consuming them later. With this method, you can customize the interval at which the messages are redelivered. Consumers on the original topic are automatically subscribed to the retry letter topic as well. Once the maximum number of retries has been reached, the unconsumed messages are moved to a [dead letter topic](#dead-letter-topic) for manual processing.
-Enable dead letter topic in a Java client using the default dead letter topic.
+The diagram below illustrates the concept of the retry letter topic.
+
+
+The intention of using retry letter topic is different from using [delayed message delivery](#delayed-message-delivery), even though both are aiming to consume a message later. Retry letter topic serves failure handling through message redelivery to ensure critical data is not lost, while delayed message delivery is intended to deliver a message with a specified time of delay.
+
+By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+
+Use the following API to consume messages from a retry letter topic. When the value of `maxRedeliverCount` is reached, the unconsumed messages are moved to a dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .build())
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The default dead letter topic uses this format:
+The default retry letter topic uses this format:
```
-<topicname>-<subscriptionname>-DLQ
+<topicname>-<subscriptionname>-RETRY
```
-Use the Java client to specify the name of the dead letter topic.
+Use the Java client to specify the name of the retry letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .build())
- .subscribe();
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .enableRetry(true)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .retryLetterTopic("my-retry-letter-topic-name")
+ .build())
+ .subscribe();
```
-By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
+The messages in the retry letter topic contain some special properties that are automatically created by the client.
+
+Special property | Description
+:--------------------|:-----------
+`REAL_TOPIC` | The real topic name.
+`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
+`RECONSUMETIMES` | The number of retries to consume messages.
+`DELAY_TIME` | Message retry interval in milliseconds.
+**Example**
+
+```
+
+REAL_TOPIC = persistent://public/default/my-topic
+ORIGIN_MESSAGE_ID = 1:0:-1:0
+RECONSUMETIMES = 6
+DELAY_TIME = 3000
+
+```
+
+Use the following API to store the messages in a retrial queue.
```java
-Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
- .subscriptionName("my-subscription")
- .subscriptionType(SubscriptionType.Shared)
- .deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .deadLetterTopic("your-topic-name")
- .initialSubscriptionName("init-sub")
- .build())
- .subscribe();
+consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
```
-Dead letter topic depends on message redelivery. 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.
+Use the following API to add custom properties for the `reconsumeLater` function. In the next attempt to consume, custom properties can be get from message#getProperty.
+
+```java
+
+Map<String, String> customProperties = new HashMap<String, String>();
+customProperties.put("custom-key-1", "custom-value-1");
+customProperties.put("custom-key-2", "custom-value-2");
+consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+
+```
:::note
-Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+* Currently, retry letter topic is enabled in Shared subscription types.
+* Compared with negative acknowledgment, retry letter topic is more suitable for messages that require a large number of retries with a configurable retry interval. Because messages in the retry letter topic are persisted to BookKeeper, while messages that need to be retried due to negative acknowledgment are cached on the client side.
:::
-### Retry letter topic
-
-For many online business systems, a message is re-consumed when exception occurs in the business logic processing. To configure the delay time for re-consuming the failed messages, you can configure the producer to send messages to both the business topic and the retry letter topic, and enable automatic retry on the consumer. With this setting, the messages that are not consumed will be stored in the retry letter topic. After the specified delay time, the consumer automatically consumes [...]
+### Dead letter topic
-By default, automatic retry is disabled. You can set `enableRetry` to `true` to enable automatic retry on the consumer.
+Dead letter topic allows you to continue message consumption even some messages are not consumed successfully. The messages that are failed to be consumed are stored in a specific topic, which is called dead letter topic. You can decide how to handle the messages in the dead letter topic.
-Use the following API to consume messages from a retry letter topic.
+Enable dead letter topic in a Java client using the default dead letter topic.
```java
Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
- .topic(topic)
+ .topic("my-topic")
.subscriptionName("my-subscription")
.subscriptionType(SubscriptionType.Shared)
- .enableRetry(true)
- .receiverQueueSize(100)
.deadLetterPolicy(DeadLetterPolicy.builder()
- .maxRedeliverCount(maxRedeliveryCount)
- .retryLetterTopic("persistent://my-property/my-ns/my-subscription-custom-Retry")
- .build())
- .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest)
+ .maxRedeliverCount(maxRedeliveryCount)
+ .build())
.subscribe();
```
-The messages in the retry letter topic contain some special properties that are automatically created by the client.
-
-Special property | Description
-:--------------------|:-----------
-`REAL_TOPIC` | The real topic name.
-`ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking.
-`RECONSUMETIMES` | The retry consume times.
-`DELAY_TIME` | Message delay timeMs.
-**Example**
+The default dead letter topic uses this format:
```
-REAL_TOPIC = persistent://public/default/my-topic
-ORIGIN_MESSAGE_ID = 1:0:-1:0
-RECONSUMETIMES = 6
-DELAY_TIME = 3000
+<topicname>-<subscriptionname>-DLQ
```
-Use the following API to store the messages in a retrial queue.
+Use the Java client to specify the name of the dead letter topic.
```java
-consumer.reconsumeLater(msg, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .build())
+ .subscribe();
```
-Use the following API to add custom properties for the `reconsumeLater` function.
+By default, there is no subscription during a DLQ topic creation. Without a just-in-time subscription to the DLQ topic, you may lose messages. To automatically create an initial subscription for the DLQ, you can specify the `initialSubscriptionName` parameter. If this parameter is set but the broker's `allowAutoSubscriptionCreation` is disabled, the DLQ producer will fail to be created.
```java
-Map<String, String> customProperties = new HashMap<String, String>();
-customProperties.put("custom-key-1", "custom-value-1");
-customProperties.put("custom-key-2", "custom-value-2");
-consumer.reconsumeLater(msg, customProperties, 3, TimeUnit.SECONDS);
+Consumer<byte[]> consumer = pulsarClient.newConsumer(Schema.BYTES)
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .deadLetterPolicy(DeadLetterPolicy.builder()
+ .maxRedeliverCount(maxRedeliveryCount)
+ .deadLetterTopic("my-dead-letter-topic-name")
+ .initialSubscriptionName("init-sub")
+ .build())
+ .subscribe();
```
+Dead letter topic serves message redelivery, which is triggered by [acknowledgement timeout](#acknowledgement-timeout) or [negative acknowledgement](#negative-acknowledgement) or [retry letter topic](#retry-letter-topic) .
+:::note
+
+* Currently, dead letter topic is enabled in Shared and Key_Shared subscription types.
+
+:::
+
## 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: