momo-jun commented on a change in pull request #14498:
URL: https://github.com/apache/pulsar/pull/14498#discussion_r824347876
##########
File path: site2/docs/concepts-messaging.md
##########
@@ -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 the negative acknowledgment caches
messages that need to be retried on the client side, and the retry letter topic
is persisted to bookkeeper.
Review comment:
```suggestion
> * 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.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
