This is an automated email from the ASF dual-hosted git repository.
sijie 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 aec968a Add subscription modes for java client doc. (#4533)
aec968a is described below
commit aec968a117311fd2d09a956a0a957bf9c8f21741
Author: lipenghui <[email protected]>
AuthorDate: Fri Jun 21 05:38:54 2019 +0800
Add subscription modes for java client doc. (#4533)
### Motivation
Add document for java client to describe how to use each subscription modes
and the difference between each subscription modes.
### Modifications
Add subscription modes section for java client doc.
### Does this pull request potentially affect one of the following parts:
*If `yes` was chosen, please highlight the changes*
- Dependencies (does it add or upgrade a dependency): (no)
- The public API: (no)
- The schema: (no)
- The default values of configurations: (no)
- The wire protocol: (no)
- The rest endpoints: (no)
- The admin cli options: (no)
- Anything that affects deployment: (no)
### Documentation
- Does this pull request introduce a new feature? (no)
---
site2/docs/client-libraries-java.md | 181 ++++++++++++++++++++++++++++++++++++
1 file changed, 181 insertions(+)
diff --git a/site2/docs/client-libraries-java.md
b/site2/docs/client-libraries-java.md
index 2a07981..35887fc 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -318,6 +318,187 @@ consumerBuilder
});
```
+### Subscription modes
+
+Pulsar has various [subscription modes](concepts-messaging#subscription-modes)
to match different scenarios. A topic can have multiple subscriptions with
different subscription modes. However, a subscription can only have one
subscription mode at a time.
+
+A subscription is identified with the subscription name, and a subscription
name can specify only one subscription mode at a time. You can change the
subscription mode, yet you have to let all existing consumers of this
subscription offline first.
+
+Different subscription modes have different message distribution modes. This
section describes the differences of subscription modes and how to use them.
+
+In order to better describe their differences, assuming you have a topic named
"my-topic", and the producer has published 10 messages.
+
+```java
+Producer<String> producer = client.newProducer(Schema.STRING)
+ .topic("my-topic")
+ .enableBatch(false)
+ .create();
+// 3 messages with "key-1", 3 messages with "key-2", 2 messages with "key-3"
and 2 messages with "key-4"
+producer.newMessage().key("key-1").value("message-1-1").send();
+producer.newMessage().key("key-1").value("message-1-2").send();
+producer.newMessage().key("key-1").value("message-1-3").send();
+producer.newMessage().key("key-2").value("message-2-1").send();
+producer.newMessage().key("key-2").value("message-2-2").send();
+producer.newMessage().key("key-2").value("message-2-3").send();
+producer.newMessage().key("key-3").value("message-3-1").send();
+producer.newMessage().key("key-3").value("message-3-2").send();
+producer.newMessage().key("key-4").value("message-4-1").send();
+producer.newMessage().key("key-4").value("message-4-2").send();
+```
+
+#### Exclusive
+
+Create a new consumer and subscribe with the `Exclusive` subscription mode.
+
+```java
+Consumer consumer = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Exclusive)
+ .subscribe()
+```
+
+Only the first consumer is allowed to the subscription, other consumers
receive an error. The first consumer receives all 10 messages, and the
consuming order is the same as the producing order.
+
+> Note:
+>
+> If topic is a partitioned topic, the first consumer subscribes to all
partitioned topics, other consumers are not assigned with partitions and
receive an error.
+
+#### Failover
+
+Create new consumers and subscribe with the`Failover` subscription mode.
+
+```java
+Consumer consumer1 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Failover)
+ .subscribe()
+Consumer consumer2 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Failover)
+ .subscribe()
+//conumser1 is the active consumer, consumer2 is the standby consumer.
+//consumer1 receives 5 messages and then crashes, consumer2 takes over as an
active consumer.
+
+
+```
+
+Multiple consumers can attach to the same subscription, yet only the first
consumer is active, and others are standby. When the active consumer is
disconnected, messages will be dispatched to one of standby consumers, and the
standby consumer becomes active consumer.
+
+If the first active consumer receives 5 messages and is disconnected, the
standby consumer becomes active consumer. Consumer1 will receive:
+
+```
+("key-1", "message-1-1")
+("key-1", "message-1-2")
+("key-1", "message-1-3")
+("key-2", "message-2-1")
+("key-2", "message-2-2")
+```
+
+consumer2 will receive:
+
+```
+("key-2", "message-2-3")
+("key-3", "message-3-1")
+("key-3", "message-3-2")
+("key-4", "message-4-1")
+("key-4", "message-4-2")
+```
+
+> Note:
+>
+> If a topic is a partitioned topic, each partition only has one active
consumer, messages of one partition only distributed to one consumer, messages
of multiple partitions are distributed to multiple consumers.
+
+#### Shared
+
+Create new consumers and subscribe with `Shared` subscription mode:
+
+```java
+Consumer consumer1 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .subscribe()
+
+Consumer consumer2 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Shared)
+ .subscribe()
+//Both consumer1 and consumer 2 is active consumers.
+```
+
+In shared subscription mode, multiple consumers can attach to the same
subscription and message are delivered in a round robin distribution across
consumers.
+
+If a broker dispatches only one message at a time, consumer1 will receive:
+
+```
+("key-1", "message-1-1")
+("key-1", "message-1-3")
+("key-2", "message-2-2")
+("key-3", "message-3-1")
+("key-4", "message-4-1")
+```
+
+consumer 2 will receive:
+
+```
+("key-1", "message-1-2")
+("key-2", "message-2-1")
+("key-2", "message-2-3")
+("key-3", "message-3-2")
+("key-4", "message-4-2")
+```
+
+`Shared` subscription is different from `Exclusive` and `Failover`
subscription modes. `Shared` subscription has better flexibility, but cannot
provide order guarantee.
+
+#### Key_shared
+
+This is a new subscription mode since 2.4.0 release, create new consumers and
subscribe with `Key_Shared` subscription mode:
+
+```java
+Consumer consumer1 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Key_Shared)
+ .subscribe()
+
+Consumer consumer2 = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscriptionType(SubscriptionType.Key_Shared)
+ .subscribe()
+//Both consumer1 and consumer2 are active consumers.
+```
+
+`Key_Shared` subscription is like `Shared` subscription, all consumers can
attach to the same subscription. But it is different from `Key_Shared`
subscription, messages with the same key are delivered to only one consumer in
order. The possible distribution of messages between different consumers(by
default we do not know in advance which keys will be assigned to a consumer,
but a key will only be assigned to a consumer at the same time. ) .
+
+consumer1 will receive:
+
+```
+("key-1", "message-1-1")
+("key-1", "message-1-2")
+("key-1", "message-1-3")
+("key-3", "message-3-1")
+("key-3", "message-3-2")
+```
+
+consumer 2 will receive:
+
+```
+("key-2", "message-2-1")
+("key-2", "message-2-2")
+("key-2", "message-2-3")
+("key-4", "message-4-1")
+("key-4", "message-4-2")
+```
+
+> Note:
+>
+> If the message key is not specified, messages without key will be dispatched
to one consumer in order by default.
+
## Reader interface
With the [reader interface](concepts-clients.md#reader-interface), Pulsar
clients can "manually position" themselves within a topic, reading all messages
from a specified message onward. The Pulsar API for Java enables you to create
{@inject: javadoc:Reader:/client/org/apache/pulsar/client/api/Reader} objects
by specifying a topic, a {@inject:
javadoc:MessageId:/client/org/apache/pulsar/client/api/MessageId}, and
{@inject: javadoc:ReaderConfiguration:/client/org/apache/pulsar/client/api [...]
