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 <[email protected]>
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:
