[pulsar] branch master updated: [doc] Clarify the impact of batch message in key_shared subscription (#7175)

[pe...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

penghui 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 958398e  [doc] Clarify the impact of batch message in key_shared subscription (#7175)
958398e is described below

commit 958398e88f34af840e21aeb90756511db13a6706
Author: lipenghui <pe...@apache.org>
AuthorDate: Fri Jun 5 15:05:11 2020 +0800

    [doc] Clarify the impact of batch message in key_shared subscription (#7175)
    
    Fixes #7121
    
    ### Motivation
    
    Following the java example at http://pulsar.apache.org/docs/en/client-libraries-java/#key_shared. The messages sometimes may send to only one consumer if the producer sends the batched messages. It's better to clarify in the doc to introduce the right way to use key_shared subscription.
    
    ### Modifications
    
    Update Java client documentation.
---
 site2/docs/client-libraries-java.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/site2/docs/client-libraries-java.md b/site2/docs/client-libraries-java.md
index dabe034..68a9256 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -608,6 +608,22 @@ consumer2 receives the follwoing information.
 ("key-4", "message-4-2")
 ```
 
+If batching is enabled at the producer side, messages with different keys are added to a batch by default. The broker will dispatch the batch to the consumer, so the default batch mechanism may break the Key_Shared subscription guaranteed message distribution semantics. The producer needs to use the `KeyBasedBatcher`.
+
+```java
+Producer producer = client.newProducer()
+        .topic("my-topic")
+        .batcherBuilder(BatcherBuilder.KEY_BASED)
+        .create();
+```
+Or the producer can disable batching.
+
+```java
+Producer producer = client.newProducer()
+        .topic("my-topic")
+        .enableBatching(false)
+        .create();
+```
 > Note:
 >
 > If the message key is not specified, messages without key are dispatched to one consumer in order by default.