[Doc] add explanations for subscription mode (apache#12745)

site2/docs/admin-api-topics.md

@@ -888,30 +888,6 @@ admin.topics().getSubscriptions(topic);
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-### Unsubscribe
-
-When a subscription does not process messages any more, you can unsubscribe it in the following ways. 
-
-<!--DOCUSAURUS_CODE_TABS-->
-<!--pulsar-admin-->
-```shell
-$ pulsar-admin topics unsubscribe \
-  --subscription my-subscription \
-  persistent://test-tenant/ns1/tp1 \
-```
-
-<!--REST API-->
-{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/:topic/subscription/:subscription|operation/deleteSubscription?version=[[pulsar:version_number]]}
-
-<!--Java-->
-```java
-String topic = "persistent://my-tenant/my-namespace/my-topic";
-String subscriptionName = "my-subscription";
-admin.topics().deleteSubscription(topic, subscriptionName);
-```
-
-<!--END_DOCUSAURUS_CODE_TABS-->
-
 ### Last Message Id
 
 You can get the last committed message ID for a persistent topic. It is available since 2.3.0 release.
@@ -1464,3 +1440,90 @@ If a message has a key, it supersedes the round robin routing policy. The follow
             return signSafeMod(PARTITION_INDEX_UPDATER.getAndIncrement(this), topicMetadata.numPartitions());
         }
 ```        
+
+## Manage subscriptions
+
+You can use [Pulsar admin API](admin-api-overview.md) to create, check, and delete subscriptions.
+
+### Create subscription
+
+You can create a subscription for a topic using one of the following methods.
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--pulsar-admin-->
+
+```shell
+pulsar-admin topics create-subscription \
+--subscription my-subscription \
+persistent://test-tenant/ns1/tp1
+```
+
+<!--REST API-->
+
+{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/subscription/:subscription|operation/createSubscriptions?version=[[pulsar:version_number]]}
+
+<!--Java-->
+
+```java
+String topic = "persistent://my-tenant/my-namespace/my-topic";
+String subscriptionName = "my-subscription";
+admin.topics().createSubscription(topic, subscriptionName, MessageId.latest);
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+### Get subscription
+
+You can check all subscription names for a given topic using one of the following methods.
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--pulsar-admin-->
+
+```shell
+pulsar-admin topics subscriptions \
+persistent://test-tenant/ns1/tp1 \
+my-subscription
+```
+
+<!--REST API-->
+
+{@inject: endpoint|GET|/admin/v2/:schema/:tenant/:namespace/:topic/subscriptions|operation/getSubscriptions?version=[[pulsar:version_number]]}
+
+<!--Java-->
+
+```java
+String topic = "persistent://my-tenant/my-namespace/my-topic";
+admin.topics().getSubscriptions(topic);
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+### Unsubscribe subscription 
+
+When a subscription does not process messages any more, you can unsubscribe it using one of the following methods. 
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--pulsar-admin-->
+
+```shell
+pulsar-admin topics unsubscribe \
+--subscription my-subscription \
+persistent://test-tenant/ns1/tp1 
+```
+
+<!--REST API-->
+
+{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/:topic/subscription/:subscription|operation/deleteSubscription?version=[[pulsar:version_number]]}
+
+<!--Java-->
+
+```java
+String topic = "persistent://my-tenant/my-namespace/my-topic";
+String subscriptionName = "my-subscription";
+admin.topics().deleteSubscription(topic, subscriptionName);
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->

site2/docs/concepts-messaging.md

@@ -316,10 +316,11 @@ A subscription is a named configuration rule that determines how messages are de
 > * If you want to achieve "message queuing" among consumers, share the same subscription name among multiple consumers(shared, failover, key_shared).
 > * If you want to achieve both effects simultaneously, combine exclusive subscription type with other subscription types for consumers.
 
-### Consumerless Subscriptions and Their Corresponding Types
+### Subscriptions type
+
 When a subscription has no consumers, its subscription type is undefined. The type of a subscription is defined when a consumer connects to it, and the type can be changed by restarting all consumers with a different configuration.
 
-### Exclusive
+#### Exclusive
 
 In *Exclusive* type, only a single consumer is allowed to attach to the subscription. If multiple consumers subscribe to a topic using the same subscription, an error occurs.
 
@@ -329,7 +330,7 @@ In the diagram below, only **Consumer A-0** is allowed to consume messages.
 
 ![Exclusive subscriptions](assets/pulsar-exclusive-subscriptions.png)
 
-### Failover
+#### Failover
 
 In *Failover* type, multiple consumers can attach to the same subscription. A master consumer is picked for non-partitioned topic or each partition of partitioned topic and receives messages. When the master consumer disconnects, all (non-acknowledged and subsequent) messages are delivered to the next consumer in line.
 
@@ -341,7 +342,7 @@ In the diagram below, **Consumer-B-0** is the master consumer while **Consumer-B
 
 ![Failover subscriptions](assets/pulsar-failover-subscriptions.png)
 
-### Shared
+#### Shared
 
 In *shared* or *round robin* type, multiple consumers can attach to the same subscription. Messages are delivered in a round robin distribution across consumers, and any given message is delivered to only one consumer. When a consumer disconnects, all the messages that were sent to it and not acknowledged will be rescheduled for sending to the remaining consumers.
 
@@ -354,7 +355,7 @@ In the diagram below, **Consumer-C-1** and **Consumer-C-2** are able to subscrib
 
 ![Shared subscriptions](assets/pulsar-shared-subscriptions.png)
 
-### Key_Shared
+#### 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.
 
@@ -396,6 +397,57 @@ producer = client.create_producer(topic='my-topic', batching_type=pulsar.Batchin
 > * You need to specify a key or orderingKey for messages.
 > * You cannot use cumulative acknowledgment with Key_Shared type.
 
+### Subscription mode
+
+#### What is subscription mode
+
+The subscription mode indicates the cursor type. 
+
+- When a subscription is created, an associated cursor is created to record the last consumed position. 
+
+- When a consumer of the subscription restarts, it can continue consuming from the last message it consumes.
+
+Subscription mode | Description | Note
+|---|---|---
+`Durable`|The cursor is durable, which retains messages and persists the current position. <br></br>If a broker restarts from a failure, it can recover the cursor from the persistent storage (BookKeeper), so that messages can continue to be consumed from the last consumed position.|`Durable` is the **default** subscription mode.
+`NonDurable`|The cursor is non-durable. <br></br>Once a broker stops, the cursor is lost and can never be recovered, so that messages **can not** continue to be consumed from the last consumed position.|Reader’s subscription mode is `NonDurable` in nature and it does not prevent data in a topic from being deleted. Reader’s subscription mode **can not** be changed. 
+
+A [subscription](#concepts-messaging.md/#subscriptions) can have one or more consumers. When a consumer subscribes to a topic, it must specify the subscription name. A durable subscription and a non-durable subscription can have the same name, they are independent of each other. If a consumer specifies a subscription which does not exist before, the subscription is automatically created.
+
+#### When to use
+
+By default, messages of a topic without any durable subscriptions are marked as deleted. If you want to prevent the messages being marked as deleted, you can create a durable subscription for this topic. In this case, only acknowledged messages are marked as deleted. For more information, see [message retention and expiry](cookbooks-retention-expiry.md).
+
+#### How to use
+
+After a consumer is created, the default subscription mode of the consumer is `Durable`. You can change the subscription mode to `NonDurable` by making changes to the consumer’s configuration.
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--Durable-->
+ 
+```java
+        Consumer<byte[]> consumer = pulsarClient.newConsumer()
+                .topic("my-topic")
+                .subscriptionName("my-sub")
+                .subscriptionMode(SubscriptionMode.Durable)
+                .subscribe();
+```
+ 
+<!--Non-durable-->
+ 
+```java
+        Consumer<byte[]> consumer = pulsarClient.newConsumer()
+                .topic("my-topic")
+                .subscriptionName("my-sub")
+                .subscriptionMode(SubscriptionMode.NonDurable)
+                .subscribe();
+```
+ 
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+For how to create, check, or delete a durable subscription, see [manage subscriptions](admin-api-topics.md/#manage-subscriptions).
+
 ## Multi-topic subscriptions
 
 When a consumer subscribes to a Pulsar topic, by default it subscribes to one specific topic, such as `persistent://public/default/my-topic`. As of Pulsar version 1.23.0-incubating, however, Pulsar consumers can simultaneously subscribe to multiple topics. You can define a list of topics in two ways: