You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
_Subscriptions_ in {pulsar-reg} describe which consumers are consuming data from a topic and how they want to consume that data.
5
7
6
8
An _exclusive subscription_ describes a basic publish-subscribe (pub-sub) pattern where a single consumer subscribes to a single topic and consumes from it.
7
9
8
10
This page explains how to use {pulsar-short}'s exclusive subscription model to manage your topic consumption.
. To configure a {pulsar-short} exclusive subscription, define a `pulsarConsumer` object in `SimplePulsarConsumer.java`, as you would for other subscription types.
16
-
However, you don't need to declare a `subscriptionType`.
17
-
Whereas other subscription types required you to declare a specific `subscriptionType`, {pulsar-short} creates an exclusive subscription by default if you don't declare a `subscriptionType`.
24
+
To create a {pulsar-short} exclusive subscription, create a `pulsarConsumer` with `{subscription-type}`.
25
+
26
+
. In `src/main/java/com/datastax/pulsar`, create a `SimplePulsarConsumer.java` file with the following contents:
If you want to explicitly define an exclusive subscription, you can add `.subscriptionType(SubscriptionType.Exclusive)` to the consumer.
34
-
35
-
. In the `pulsar-subscription-example` project, run `SimplePulsarConsumer.java` to begin consuming messages.
36
-
+
37
-
The confirmation message and a cursor appear to indicate the consumer is ready:
34
+
Alternatively, you can omit the `.subscriptionType` declaration because `Exclusive` is the default subscription type:
38
35
+
39
-
.Result
40
-
[source,console]
36
+
.SimplePulsarConsumer.java with implied exclusive subscription
37
+
[source,java]
41
38
----
42
-
[main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
43
-
...
44
-
[pulsar-client-io-1-1] INFO org.apache.pulsar.client.impl.ConsumerImpl - [persistent://<tenant_name>/<namespace>/in][SimplePulsarConsumer] Subscribed to topic on <service_url> -- consumer: 0
To try out a {pulsar-short} failover subscription, add `.subscriptionType(SubscriptionType.Failover)` to the `pulsarConsumer` in `SimplePulsarConsumer.java`:
26
+
To create a {pulsar-short} failover subscription, create a `pulsarConsumer` with `{subscription-type}`.
19
27
28
+
. In `src/main/java/com/datastax/pulsar`, create a `SimplePulsarConsumer.java` file with the following contents:
. In the `pulsar-subscription-example` project, run `SimplePulsarConsumer.java` to begin consuming messages as the primary consumer.
36
-
+
37
-
The confirmation message and a cursor appear to indicate the consumer is ready:
38
-
+
39
-
.Result
40
-
[source,console]
41
-
----
42
-
[main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
43
-
...
44
-
[pulsar-client-io-1-1] INFO org.apache.pulsar.client.impl.ConsumerImpl - [persistent://<tenant_name>/<namespace>/in][SimplePulsarConsumer] Subscribed to topic on <service_url> -- consumer: 0
To create a {pulsar-short} key shared subscription, create a `pulsarConsumer` with `{subscription-type}` and a `keySharedPolicy` configuration.
31
+
The `keySharedPolicy` defines how hashed values are assigned to subscribed consumers.
32
+
33
+
For the simplest configuration, use the `<<use-autosplithashrange,autoSplitHashRange>>` policy.
34
+
35
+
If you need to set fixed hash ranges, use the `<<use-stickyhashrange,stickyHashRange>>` policy.
36
+
37
+
[#use-autosplithashrange]
38
+
=== Use autoSplitHashRange
39
+
40
+
To automatically assign hash ranges to consumers, use the `autoSplitHashRange` policy.
41
+
Running multiple consumers with `autoSplitHashRange` balances the messaging load across all available consumers, like a xref:astream-subscriptions-shared.adoc[shared subscription].
21
42
22
-
. To try out a {pulsar-short} key shared subscription, add `.subscriptionType(SubscriptionType.Key_Shared)` to the `pulsarConsumer` in `SimplePulsarConsumer.java`:
43
+
. In `src/main/java/com/datastax/pulsar`, create a `SimplePulsarConsumer.java` file with the following contents:
23
44
+
24
45
.SimplePulsarConsumer.java
25
-
[source,java]
46
+
[source,java,subs="+attributes"]
47
+
----
48
+
include::ROOT:partial$simplepulsarconsumer.java[]
49
+
----
50
+
51
+
. In `pulsarConsumer`, add `.keySharedPolicy(KeySharedPolicy.autoSplitHashRange())`:
52
+
+
53
+
.SimplePulsarConsumer.java with autoSplitHashRange
To set a fixed hash range, use the `stickyHashRange` policy.
79
+
This policy requires additional dependencies and producer configuration changes, in addition to the consumer configuration.
80
+
81
+
. In `src/main/java/com/datastax/pulsar`, create a `SimplePulsarConsumer.java` file with the following contents:
39
82
+
40
-
The `keySharedPolicy` defines how hashed values are assigned to subscribed consumers.
41
-
+
42
-
The above example uses `autoSplitHashRange`, which is an auto-hashing policy.
43
-
Running multiple consumers with auto-hashing balances the messaging load across all available consumers, like a xref:astream-subscriptions-shared.adoc[shared subscription].
44
-
+
45
-
If you want to set a fixed hash range, use `KeySharedPolicy.stickyHashRange()`, as demonstrated in the following steps.
83
+
.SimplePulsarConsumer.java
84
+
[source,java,subs="+attributes"]
85
+
----
86
+
include::ROOT:partial$simplepulsarconsumer.java[]
87
+
----
46
88
47
-
. To use a sticky hashed key shared subscription, import the following classes to `SimplePulsarConsumer.java`:
89
+
. Import the following additional classes that are required for the `stickyHashRange` policy:
. In the `pulsar-examples` project, run `SimplePulsarConsumer.java` to begin consuming messages.
93
-
+
94
-
The confirmation message and a cursor appear to indicate the consumer is ready:
95
-
+
96
-
.Result
97
-
[source,console]
98
-
----
99
-
[main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
100
-
...
101
-
[pulsar-client-io-1-1] INFO org.apache.pulsar.client.impl.ConsumerImpl - [persistent://<tenant_name>/<namespace>/in][SimplePulsarConsumer] Subscribed to topic on <service_url> -- consumer: 0
. In a new terminal window, run `SimplePulsarProducer.java` to begin producing messages:
105
169
+
@@ -123,9 +187,13 @@ In the `SimplePulsarConsumer` terminal, the consumer begins receiving messages:
123
187
124
188
. In a new terminal window, try to run a new instance of `SimplePulsarConsumer.java`.
125
189
+
126
-
The new consumer cannot subscribe to the topic because the `SimplePulsarConsumer` configuration reserved the entire hash range for the first consumer:
190
+
If you used `autoSplitHashRange`, then the new consumer subscribes to the topic and consumes messages.
191
+
The auto-hashing policy balances hash ranges across available consumers.
127
192
+
128
-
.Result
193
+
If you used sticky hashing with one `Range.of()` argument, then the new consumer cannot subscribe to the topic because the `SimplePulsarConsumer` configuration reserved the entire hash range for the first consumer.
194
+
For example:
195
+
+
196
+
.Result when using sticky hashing limited to one consumer
129
197
[source,console]
130
198
----
131
199
[main] INFO com.datastax.pulsar.Configuration - Configuration has been loaded successfully
at org.apache.pulsar.client.impl.ConsumerBuilderImpl.subscribe(ConsumerBuilderImpl.java:101)
138
206
at com.datastax.pulsar.SimplePulsarConsumer.main(SimplePulsarConsumer.java:47)
139
207
----
140
-
141
-
. To run multiple consumers with sticky hashing, modify the `SimplePulsarConsumer.java` configuration to split the hash range between consumers or use auto-hashing.
208
+
+
209
+
To run multiple consumers with sticky hashing, you must modify `SimplePulsarConsumer.java` to split the hash range between consumers, as explained in <<use-stickyhashrange>>.
142
210
Then, you can launch multiple instances of `SimplePulsarConsumer.java` to consume messages from different hash ranges.
0 commit comments