This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 09be7974247 [improve][docs] Improve examples and language (#16057)
09be7974247 is described below
commit 09be79742473b7686f44d3f47e7c10fb9b441792
Author: Dave Maughan <[email protected]>
AuthorDate: Tue Jun 21 14:48:16 2022 +0100
[improve][docs] Improve examples and language (#16057)
---
site2/docs/concepts-messaging.md | 39 +++++++++++++++++++++------------------
1 file changed, 21 insertions(+), 18 deletions(-)
diff --git a/site2/docs/concepts-messaging.md b/site2/docs/concepts-messaging.md
index af34e087aef..72d232d0dae 100644
--- a/site2/docs/concepts-messaging.md
+++ b/site2/docs/concepts-messaging.md
@@ -102,7 +102,7 @@ You can compress messages published by producers during
transportation. Pulsar c
When batching is enabled, the producer accumulates and sends a batch of
messages in a single request. The batch size is defined by the maximum number
of messages and the maximum publish latency. Therefore, the backlog size
represents the total number of batches instead of the total number of messages.
-In Pulsar, batches are tracked and stored as single units rather than as
individual messages. Consumer unbundles a batch into individual messages.
However, scheduled messages (configured through the `deliverAt` or the
`deliverAfter` parameter) are always sent as individual messages even batching
is enabled.
+In Pulsar, batches are tracked and stored as single units rather than as
individual messages. Consumers unbundle a batch into individual messages.
However, scheduled messages (configured through the `deliverAt` or the
`deliverAfter` parameter) are always sent as individual messages even when
batching is enabled.
In general, a batch is acknowledged when all of its messages are acknowledged
by a consumer. It means that when **not all** batch messages are acknowledged,
then unexpected failures, negative acknowledgements, or acknowledgement
timeouts can result in a redelivery of all messages in this batch.
@@ -254,6 +254,7 @@ Consumer<byte[]> consumer = pulsarClient.newConsumer()
.negativeAckRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
.minDelayMs(1000)
.maxDelayMs(60 * 1000)
+ .multiplier(2)
.build())
.subscribe();
@@ -263,14 +264,15 @@ 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
+1 | 1 seconds
+2 | 2 seconds
+3 | 4 seconds
+4 | 8 seconds
+5 | 16 seconds
+6 | 32 seconds
+7 | 60 seconds
+8 | 60 seconds
+
:::note
If batching is enabled, all messages in one batch are redelivered to the
consumer.
@@ -293,8 +295,9 @@ If you want to use redelivery backoff, you can use the
following API.
consumer.ackTimeout(10, TimeUnit.SECOND)
.ackTimeoutRedeliveryBackoff(MultiplierRedeliveryBackoff.builder()
.minDelayMs(1000)
- .maxDelayMs(60000)
- .multiplier(2).build())
+ .maxDelayMs(60 * 1000)
+ .multiplier(2)
+ .build())
```
@@ -345,7 +348,7 @@ The retry letter topic allows you to store the messages
that failed to be consum
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.
+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 delay.
By default, automatic retry is disabled. You can set `enableRetry` to `true`
to enable automatic retry on the consumer.
@@ -437,7 +440,7 @@ consumer.reconsumeLater(msg, customProperties, 3,
TimeUnit.SECONDS);
### 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.
+Dead letter topic allows you to continue message consumption even when some
messages are not consumed successfully. The messages that have failed to be
consumed are stored in a specific topic, which is called the dead letter topic.
You can decide how to handle the messages in the dead letter topic.
Enable dead letter topic in a Java client using the default dead letter topic.
@@ -478,7 +481,7 @@ Consumer<byte[]> consumer =
pulsarClient.newConsumer(Schema.BYTES)
```
-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.
+By default, there is no subscription during 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
@@ -495,7 +498,7 @@ Consumer<byte[]> consumer =
pulsarClient.newConsumer(Schema.BYTES)
```
-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) .
+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.
@@ -516,7 +519,7 @@ Topic name component | Description
:--------------------|:-----------
`persistent` / `non-persistent` | This identifies the type of topic. Pulsar
supports two kind of topics:
[persistent](concepts-architecture-overview.md#persistent-storage) and
[non-persistent](#non-persistent-topics). The default is persistent, so if you
do not specify a type, the topic is persistent. With persistent topics, all
messages are durably persisted on disks (if the broker is not standalone,
messages are durably persisted on multiple disks), whereas data for
non-persistent topi [...]
`tenant` | The topic tenant within the instance. Tenants are
essential to multi-tenancy in Pulsar, and spread across clusters.
-`namespace` | The administrative unit of the topic, which acts as a
grouping mechanism for related topics. Most topic configuration is performed at
the [namespace](#namespaces) level. Each tenant has one or multiple namespaces.
+`namespace` | The administrative unit of the topic, which acts as a
grouping mechanism for related topics. Most topic configuration is performed at
the [namespace](#namespaces) level. Each tenant has one or more namespaces.
`topic` | The final part of the name. Topic names have no special
meaning in a Pulsar instance.
> **No need to explicitly create new topics**
@@ -525,7 +528,7 @@ Topic name component | Description
## Namespaces
-A namespace is a logical nomenclature within a tenant. A tenant creates
multiple namespaces via the [admin API](admin-api-namespaces.md#create). For
instance, a tenant with different applications can create a separate namespace
for each application. A namespace allows the application to create and manage a
hierarchy of topics. The topic `my-tenant/app1` is a namespace for the
application `app1` for `my-tenant`. You can create any number of
[topics](#topics) under the namespace.
+A namespace is a logical nomenclature within a tenant. A tenant creates
namespaces via the [admin API](admin-api-namespaces.md#create). For instance, a
tenant with different applications can create a separate namespace for each
application. A namespace allows the application to create and manage a
hierarchy of topics. The topic `my-tenant/app1` is a namespace for the
application `app1` for `my-tenant`. You can create any number of
[topics](#topics) under the namespace.
## Subscriptions
@@ -582,7 +585,7 @@ In the diagram below, **Consumer-C-1** and **Consumer-C-2**
are able to subscrib
#### Key_Shared
-In *Key_Shared* type, multiple consumers can attach to the same subscription.
Messages are delivered in a distribution across consumers and message with same
key or same ordering key are delivered to only one consumer. No matter how many
times the message is re-delivered, it is delivered to the same consumer. When a
consumer connected or disconnected will cause served consumer change for some
key of message.
+In *Key_Shared* type, multiple consumers can attach to the same subscription.
Messages are delivered in a distribution across consumers and messages with the
same key or same ordering key are delivered to only one consumer. No matter how
many times the message is re-delivered, it is delivered to the same consumer.
When a consumer connects or disconnects, it causes the served consumer to
change some message keys.
