[improve][doc] Improve the description of acknowledgment timeout in J…

…ava docs and REST API links (#16746)
apache · Aug 31, 2022 · f89295d · f89295d
1 parent 856ef15
commit f89295d
Show file tree

Hide file tree

Showing 47 changed files with 232 additions and 789 deletions.
diff --git a/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java b/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java
@@ -181,9 +181,11 @@ public interface ConsumerBuilder<T> extends Cloneable {
      * Set the timeout for unacked messages, truncated to the nearest millisecond. The timeout needs to be greater than
      * 1 second.
      *
-     * <p>By default, the acknowledge timeout is disabled and that means that messages delivered to a
-     * consumer is not re-delivered unless the consumer crashes. Since 2.3.0, when a dead letter policy
-     * is specified, and no ackTimeoutMillis is specified, the ack timeout is set to 30 seconds.
+     * <p>By default, the acknowledge timeout is disabled (set to `0`, which means infinite).
+     * When a consumer with an infinite acknowledgment timeout terminates, any unacknowledged
+     * messages that it receives are re-delivered to another consumer.
+     * Since 2.3.0, when a dead letter policy is specified and no ackTimeoutMillis is specified,
+     * the ack timeout is set to 30 seconds.
      *
      * <p>When enabling ack timeout, if a message is not acknowledged within the specified timeout
      * it is re-delivered to the consumer (possibly to a different consumer in case of

diff --git a/site2/docs/admin-api-topics.md b/site2/docs/admin-api-topics.md
@@ -1105,7 +1105,7 @@ $ pulsar-admin topics lookup \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/lookup/v2/topic/:topic_domain/:tenant/:namespace/:topic|operation/lookupTopicAsync?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/lookup/v2/topic/:topic-domain/:tenant/:namespace/:topic|operation/lookupTopicAsync?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java">

diff --git a/site2/docs/io-use.md b/site2/docs/io-use.md
@@ -764,7 +764,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace/|operation/listSources?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace|operation/listSources?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -823,7 +823,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace/|operation/listSinks?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace|operation/listSinks?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">

diff --git a/site2/docs/reference-rest-api-overview.md b/site2/docs/reference-rest-api-overview.md
@@ -16,4 +16,5 @@ Pulsar provides a variety of REST APIs that enable you to interact with Pulsar t
 | [Sinks](/sink-rest-api/?version=master) | REST APIs for sink-specific operations.|
 | [Packages](/packages-rest-api/?version=master) | REST APIs for package-specific operations. A package can be a group of functions, sources, and sinks.|
 | [Transactions](/transactions-rest-api/?version=master) | REST APIs for transaction-specific operations.|
+| [Lookup](/lookup-rest-api/?version=master) | REST APIs for lookup-specific operations, such as getting the owner broker of a topic, getting the namespace bundle that a topic belongs to, and so on.|
 
diff --git a/site2/website/versioned_docs/version-2.10.0-deprecated/admin-api-namespaces.md b/site2/website/versioned_docs/version-2.10.0-deprecated/admin-api-namespaces.md
@@ -554,7 +554,7 @@ $ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenan
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/{bundle}/split|operation/splitNamespaceBundle?version=@pulsar:version_number@}
+{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/:bundle/split|operation/splitNamespaceBundle?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java">

diff --git a/site2/website/versioned_docs/version-2.10.0-deprecated/io-use.md b/site2/website/versioned_docs/version-2.10.0-deprecated/io-use.md
@@ -766,7 +766,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace/|operation/listSources?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace|operation/listSources?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -825,7 +825,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace/|operation/listSinks?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace|operation/listSinks?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">

diff --git a/site2/website/versioned_docs/version-2.10.1-deprecated/admin-api-namespaces.md b/site2/website/versioned_docs/version-2.10.1-deprecated/admin-api-namespaces.md
@@ -554,7 +554,7 @@ $ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenan
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/{bundle}/split|operation/splitNamespaceBundle?version=@pulsar:version_number@}
+{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/:bundle/split|operation/splitNamespaceBundle?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java">

diff --git a/site2/website/versioned_docs/version-2.10.1-deprecated/io-use.md b/site2/website/versioned_docs/version-2.10.1-deprecated/io-use.md
@@ -766,7 +766,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace/|operation/listSources?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sources/:tenant/:namespace|operation/listSources?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -825,7 +825,7 @@ For the latest and complete information, see [Pulsar admin docs](/tools/pulsar-a
 </TabItem>
 <TabItem value="REST API">
 
-Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace/|operation/listSinks?version=@pulsar:version_number@}
+Send a `GET` request to this endpoint: {@inject: endpoint|GET|/admin/v3/sinks/:tenant/:namespace|operation/listSinks?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">

diff --git a/site2/website/versioned_docs/version-2.7.0/admin-api-functions.md b/site2/website/versioned_docs/version-2.7.0/admin-api-functions.md
@@ -59,7 +59,7 @@ $ pulsar-admin functions create \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName|operation/registerFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -115,7 +115,7 @@ $ pulsar-admin functions update \
 </TabItem>
 <TabItem value="REST Admin API">
 
-{@inject: endpoint|PUT|/admin/v3/functions/:tenant/:namespace/:functionName?version=@pulsar:version_number@}
+{@inject: endpoint|PUT|/admin/v3/functions/:tenant/:namespace/:functionName|operation/updateFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -165,7 +165,7 @@ $ pulsar-admin functions start \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/start?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/start|operation/startFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -207,7 +207,7 @@ $ pulsar-admin functions start \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/start?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/start|operation/startFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java">
@@ -250,7 +250,7 @@ $ pulsar-admin functions stop \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stop?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stop|operation/stopFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -292,7 +292,7 @@ $ pulsar-admin functions stop \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/stop?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/stop|operation/stopFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -335,7 +335,7 @@ $ pulsar-admin functions restart \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/restart?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/restart|operation/restartFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -377,7 +377,7 @@ $ pulsar-admin functions restart \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/restart?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/restart|operation/restartFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -418,7 +418,7 @@ $ pulsar-admin functions list \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace|operation/listFunctions?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -460,7 +460,7 @@ $ pulsar-admin functions delete \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|DELETE|/admin/v3/functions/:tenant/:namespace/:functionName?version=@pulsar:version_number@}
+{@inject: endpoint|DELETE|/admin/v3/functions/:tenant/:namespace/:functionName|operation/deregisterFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -502,7 +502,7 @@ $ pulsar-admin functions get \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName|operation/getFunctionInfo?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -586,7 +586,7 @@ $ pulsar-admin functions status \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/status?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/status|operation/getFunctionInstanceStatus?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -628,7 +628,7 @@ $ pulsar-admin functions stats \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stats?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stats|operation/getFunctionInstanceStats?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -670,7 +670,7 @@ $ pulsar-admin functions stats \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/stats?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/stats|operation/getFunctionStats?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -715,7 +715,7 @@ $ pulsar-admin functions trigger \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/trigger?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/trigger|operation/triggerFunction?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -758,7 +758,7 @@ $ pulsar-admin functions putstate \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/state/:key?version=@pulsar:version_number@}
+{@inject: endpoint|POST|/admin/v3/functions/:tenant/:namespace/:functionName/state/:key|operation/putFunctionState?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin API">
@@ -803,7 +803,7 @@ $ pulsar-admin functions querystate \
 </TabItem>
 <TabItem value="REST API">
 
-{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/state/:key?version=@pulsar:version_number@}
+{@inject: endpoint|GET|/admin/v3/functions/:tenant/:namespace/:functionName/state/:key|operation/getFunctionState?version=@pulsar:version_number@}
 
 </TabItem>
 <TabItem value="Java Admin CLI">