This is an automated email from the ASF dual-hosted git repository.
hjf 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 1c7ca15 update client concepts (#9050)
1c7ca15 is described below
commit 1c7ca159d402dcf1a9865410f4872a5741630609
Author: sijia-w <[email protected]>
AuthorDate: Mon Dec 28 01:37:57 2020 +0100
update client concepts (#9050)
---
site2/docs/concepts-clients.md | 27 ++++++++++------------
.../version-2.7.0/concepts-clients.md | 27 ++++++++++------------
2 files changed, 24 insertions(+), 30 deletions(-)
diff --git a/site2/docs/concepts-clients.md b/site2/docs/concepts-clients.md
index cb59e3f..668891f 100644
--- a/site2/docs/concepts-clients.md
+++ b/site2/docs/concepts-clients.md
@@ -4,26 +4,26 @@ title: Pulsar Clients
sidebar_label: Clients
---
-Pulsar exposes a client API with language bindings for
[Java](client-libraries-java.md), [Go](client-libraries-go.md),
[Python](client-libraries-python.md) and [C++](client-libraries-cpp.md). The
client API optimizes and encapsulates Pulsar's client-broker communication
protocol and exposes a simple and intuitive API for use by applications.
+Pulsar exposes a client API with language bindings for
[Java](client-libraries-java.md), [Go](client-libraries-go.md),
[Python](client-libraries-python.md) and [C++](client-libraries-cpp.md). The
client API optimizes and encapsulates Pulsar's client-broker communication
protocol and exposes a simple and intuitive API for use by applications.
Under the hood, the current official Pulsar client libraries support
transparent reconnection and/or connection failover to brokers, queuing of
messages until acknowledged by the broker, and heuristics such as connection
retries with backoff.
-> #### Custom client libraries
-> If you'd like to create your own client library, we recommend consulting the
documentation on Pulsar's custom [binary
protocol](developing-binary-protocol.md)
+> **Custom client libraries**
+> If you'd like to create your own client library, we recommend consulting the
documentation on Pulsar's custom [binary
protocol](developing-binary-protocol.md).
## Client setup phase
-When an application wants to create a producer/consumer, the Pulsar client
library will initiate a setup phase that is composed of two steps:
+Before an application creates a producer/consumer, the Pulsar client library
needs to initiate a setup phase including two steps:
-1. The client will attempt to determine the owner of the topic by sending an
HTTP lookup request to the broker. The request could reach one of the active
brokers which, by looking at the (cached) zookeeper metadata will know who is
serving the topic or, in case nobody is serving it, will try to assign it to
the least loaded broker.
-1. Once the client library has the broker address, it will create a TCP
connection (or reuse an existing connection from the pool) and authenticate it.
Within this connection, client and broker exchange binary commands from a
custom protocol. At this point the client will send a command to create
producer/consumer to the broker, which will comply after having validated the
authorization policy.
+1. The client attempts to determine the owner of the topic by sending an HTTP
lookup request to the broker. The request could reach one of the active brokers
which, by looking at the (cached) zookeeper metadata knows who is serving the
topic or, in case nobody is serving it, tries to assign it to the least loaded
broker.
+1. Once the client library has the broker address, it creates a TCP connection
(or reuse an existing connection from the pool) and authenticates it. Within
this connection, client and broker exchange binary commands from a custom
protocol. At this point the client sends a command to create producer/consumer
to the broker, which will comply after having validated the authorization
policy.
-Whenever the TCP connection breaks, the client will immediately re-initiate
this setup phase and will keep trying with exponential backoff to re-establish
the producer or consumer until the operation succeeds.
+Whenever the TCP connection breaks, the client immediately re-initiates this
setup phase and keeps trying with exponential backoff to re-establish the
producer or consumer until the operation succeeds.
## Reader interface
-In Pulsar, the "standard" [consumer
interface](concepts-messaging.md#consumers) involves using consumers to listen
on [topics](reference-terminology.md#topic), process incoming messages, and
finally acknowledge those messages when they've been processed. Whenever a new
subscription is created, it is initially positioned at the end of the topic (by
default), and consumers associated with that subscription will begin reading
with the first message created afterwards. Whenever a consumer [...]
+In Pulsar, the "standard" [consumer
interface](concepts-messaging.md#consumers) involves using consumers to listen
on [topics](reference-terminology.md#topic), process incoming messages, and
finally acknowledge those messages when they are processed. Whenever a new
subscription is created, it is initially positioned at the end of the topic (by
default), and consumers associated with that subscription begin reading with
the first message created afterwards. Whenever a consumer connects t [...]
The **reader interface** for Pulsar enables applications to manually manage
cursors. When you use a reader to connect to a topic---rather than a
consumer---you need to specify *which* message the reader begins reading from
when it connects to a topic. When connecting to a topic, the reader interface
enables you to begin with:
@@ -37,15 +37,12 @@ Internally, the reader interface is implemented as a
consumer using an exclusive
[ **IMPORTANT** ]
-Unlike subscription/consumer, readers are non-durable in nature and will not
prevent data in a topic from being deleted, thus it is ***strongly*** advised
that [data retention](cookbooks-retention-expiry.md) be configured. If data
retention for a topic is not configured for an adequate amount of time,
messages that the reader has not yet read might be deleted . This will cause
readers to essentially skip messages. Configuring the data retention for a
topic guarantees the reader with [...]
+Unlike subscription/consumer, readers are non-durable in nature and does not
prevent data in a topic from being deleted, thus it is ***strongly*** advised
that [data retention](cookbooks-retention-expiry.md) be configured. If data
retention for a topic is not configured for an adequate amount of time,
messages that the reader has not yet read might be deleted . This causes the
readers to essentially skip messages. Configuring the data retention for a
topic guarantees the reader with a c [...]
-Please also note that a reader can have a "backlog", but the metric is just to
allow users to know how behind the reader is and is not considered for any
backlog quota calculations.
+Please also note that a reader can have a "backlog", but the metric is only
used for users to know how behind the reader is. The metric is not considered
for any backlog quota calculations.
-> ### Non-partitioned topics only
-> The reader interface for Pulsar cannot currently be used with [partitioned
topics](concepts-messaging.md#partitioned-topics).
-
Here's a Java example that begins reading from the earliest available message
on a topic:
```java
@@ -66,7 +63,7 @@ while (true) {
}
```
-To create a reader that will read from the latest available message:
+To create a reader that reads from the latest available message:
```java
Reader<byte[]> reader = pulsarClient.newReader()
@@ -75,7 +72,7 @@ Reader<byte[]> reader = pulsarClient.newReader()
.create();
```
-To create a reader that will read from some message between earliest and
latest:
+To create a reader that reads from some message between the earliest and the
latest:
```java
byte[] msgIdBytes = // Some byte array
diff --git a/site2/website/versioned_docs/version-2.7.0/concepts-clients.md
b/site2/website/versioned_docs/version-2.7.0/concepts-clients.md
index ef5801d..2f99174 100644
--- a/site2/website/versioned_docs/version-2.7.0/concepts-clients.md
+++ b/site2/website/versioned_docs/version-2.7.0/concepts-clients.md
@@ -5,26 +5,26 @@ sidebar_label: Clients
original_id: concepts-clients
---
-Pulsar exposes a client API with language bindings for
[Java](client-libraries-java.md), [Go](client-libraries-go.md),
[Python](client-libraries-python.md) and [C++](client-libraries-cpp.md). The
client API optimizes and encapsulates Pulsar's client-broker communication
protocol and exposes a simple and intuitive API for use by applications.
+Pulsar exposes a client API with language bindings for
[Java](client-libraries-java.md), [Go](client-libraries-go.md),
[Python](client-libraries-python.md) and [C++](client-libraries-cpp.md). The
client API optimizes and encapsulates Pulsar's client-broker communication
protocol and exposes a simple and intuitive API for use by applications.
Under the hood, the current official Pulsar client libraries support
transparent reconnection and/or connection failover to brokers, queuing of
messages until acknowledged by the broker, and heuristics such as connection
retries with backoff.
-> #### Custom client libraries
-> If you'd like to create your own client library, we recommend consulting the
documentation on Pulsar's custom [binary
protocol](developing-binary-protocol.md)
+> **Custom client libraries**
+> If you'd like to create your own client library, we recommend consulting the
documentation on Pulsar's custom [binary
protocol](developing-binary-protocol.md).
## Client setup phase
-When an application wants to create a producer/consumer, the Pulsar client
library will initiate a setup phase that is composed of two steps:
+Before an application creates a producer/consumer, the Pulsar client library
needs to initiate a setup phase including two steps:
-1. The client will attempt to determine the owner of the topic by sending an
HTTP lookup request to the broker. The request could reach one of the active
brokers which, by looking at the (cached) zookeeper metadata will know who is
serving the topic or, in case nobody is serving it, will try to assign it to
the least loaded broker.
-1. Once the client library has the broker address, it will create a TCP
connection (or reuse an existing connection from the pool) and authenticate it.
Within this connection, client and broker exchange binary commands from a
custom protocol. At this point the client will send a command to create
producer/consumer to the broker, which will comply after having validated the
authorization policy.
+1. The client attempts to determine the owner of the topic by sending an HTTP
lookup request to the broker. The request could reach one of the active brokers
which, by looking at the (cached) zookeeper metadata knows who is serving the
topic or, in case nobody is serving it, tries to assign it to the least loaded
broker.
+1. Once the client library has the broker address, it creates a TCP connection
(or reuse an existing connection from the pool) and authenticates it. Within
this connection, client and broker exchange binary commands from a custom
protocol. At this point the client sends a command to create producer/consumer
to the broker, which will comply after having validated the authorization
policy.
-Whenever the TCP connection breaks, the client will immediately re-initiate
this setup phase and will keep trying with exponential backoff to re-establish
the producer or consumer until the operation succeeds.
+Whenever the TCP connection breaks, the client immediately re-initiates this
setup phase and keeps trying with exponential backoff to re-establish the
producer or consumer until the operation succeeds.
## Reader interface
-In Pulsar, the "standard" [consumer
interface](concepts-messaging.md#consumers) involves using consumers to listen
on [topics](reference-terminology.md#topic), process incoming messages, and
finally acknowledge those messages when they've been processed. Whenever a new
subscription is created, it is initially positioned at the end of the topic (by
default), and consumers associated with that subscription will begin reading
with the first message created afterwards. Whenever a consumer [...]
+In Pulsar, the "standard" [consumer
interface](concepts-messaging.md#consumers) involves using consumers to listen
on [topics](reference-terminology.md#topic), process incoming messages, and
finally acknowledge those messages when they are processed. Whenever a new
subscription is created, it is initially positioned at the end of the topic (by
default), and consumers associated with that subscription begin reading with
the first message created afterwards. Whenever a consumer connects t [...]
The **reader interface** for Pulsar enables applications to manually manage
cursors. When you use a reader to connect to a topic---rather than a
consumer---you need to specify *which* message the reader begins reading from
when it connects to a topic. When connecting to a topic, the reader interface
enables you to begin with:
@@ -38,15 +38,12 @@ Internally, the reader interface is implemented as a
consumer using an exclusive
[ **IMPORTANT** ]
-Unlike subscription/consumer, readers are non-durable in nature and will not
prevent data in a topic from being deleted, thus it is ***strongly*** advised
that [data retention](cookbooks-retention-expiry.md) be configured. If data
retention for a topic is not configured for an adequate amount of time,
messages that the reader has not yet read might be deleted . This will cause
readers to essentially skip messages. Configuring the data retention for a
topic guarantees the reader with [...]
+Unlike subscription/consumer, readers are non-durable in nature and does not
prevent data in a topic from being deleted, thus it is ***strongly*** advised
that [data retention](cookbooks-retention-expiry.md) be configured. If data
retention for a topic is not configured for an adequate amount of time,
messages that the reader has not yet read might be deleted . This causes the
readers to essentially skip messages. Configuring the data retention for a
topic guarantees the reader with a c [...]
-Please also note that a reader can have a "backlog", but the metric is just to
allow users to know how behind the reader is and is not considered for any
backlog quota calculations.
+Please also note that a reader can have a "backlog", but the metric is only
used for users to know how behind the reader is. The metric is not considered
for any backlog quota calculations.
-> ### Non-partitioned topics only
-> The reader interface for Pulsar cannot currently be used with [partitioned
topics](concepts-messaging.md#partitioned-topics).
-
Here's a Java example that begins reading from the earliest available message
on a topic:
```java
@@ -67,7 +64,7 @@ while (true) {
}
```
-To create a reader that will read from the latest available message:
+To create a reader that reads from the latest available message:
```java
Reader<byte[]> reader = pulsarClient.newReader()
@@ -76,7 +73,7 @@ Reader<byte[]> reader = pulsarClient.newReader()
.create();
```
-To create a reader that will read from some message between earliest and
latest:
+To create a reader that reads from some message between the earliest and the
latest:
```java
byte[] msgIdBytes = // Some byte array
