[GitHub] sijie commented on a change in pull request #3263: Improve documentation for message routing mode

[GitBox <gi...@apache.org>]

sijie commented on a change in pull request #3263: Improve documentation for message routing mode
URL: https://github.com/apache/pulsar/pull/3263#discussion_r244380564
 
 

 ##########
 File path: site2/docs/concepts-messaging.md
 ##########
 @@ -199,15 +199,22 @@ Partitioned topics need to be explicitly created via the [admin API](admin-api-o
 
 When publishing to partitioned topics, you must specify a *routing mode*. The routing mode determines which partition---that is, which internal topic---each message should be published to.
 
-There are three routing modes available by default:
+There are three {@inject: javadoc:MessageRoutingMode:/client/org/apache/pulsar/client/api/MessageRoutingMode} available by default:
 
-Mode | Description | Ordering guarantee
-:----|:------------|:------------------
-Key hash | If a key property has been specified on the message, the partitioned producer will hash the key and assign it to a particular partition. | Per-key-bucket ordering
-Single default partition | If no key is provided, each producer's message will be routed to a dedicated partition, initially random selected | Per-producer ordering
-Round robin distribution | If no key is provided, all messages will be routed to different partitions in round-robin fashion to achieve maximum throughput. | None
+Mode     | Description 
+:--------|:------------
+RoundRobinPartition | Publish messages across all partitions in round-robin fashion to achieve maximum throughput. This is the default mode. 
+SinglePartition     | If no key is provided, the producer will chose one single partition and publish all the messages into that partition. While if a key is specified on the message, the partitioned producer will hash the key and assign message to a particular partition.
+CustomPartition     | Use custom message router implementation that will be called to determine the partition for a particular message. User can create a custom routing mode by using the [Java client](client-libraries-java.md) and implementing the {@inject: javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter} interface.
 
-In addition to these default modes, you can also create a custom routing mode if you're using the [Java client](client-libraries-java.md) by implementing the {@inject: javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter} interface.
+### Ordering guarantee
+
+The ordering of messages is related to MessageRoutingMode above. Usually, user would want an ordering of Per-key-bucket guarantee.
 
 Review comment:
   Also it might be worth having a section documenting about HashingScheme.
   
   - what hashing schemes are available?
   - what is the default value?
   - what should be paid attention? for example, the default hashing scheme is `JavaStringHash`, which is not useful when producers can be from different multiple language clients. It is recommended to use Murmur3_32Hash.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services