This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new a7cd17d7152 [Doc] Add C++ doc for client and producer (#515)
a7cd17d7152 is described below
commit a7cd17d7152e28d9ee7c502eef2d6f9c29c342ba
Author: Zike Yang <[email protected]>
AuthorDate: Fri Apr 14 17:50:16 2023 +0800
[Doc] Add C++ doc for client and producer (#515)
---
docs/client-libraries-clients.md | 12 +-
docs/client-libraries-producers.md | 230 ++++++++++++++++++++++++++++++-------
2 files changed, 197 insertions(+), 45 deletions(-)
diff --git a/docs/client-libraries-clients.md b/docs/client-libraries-clients.md
index 7bdda1d5952..cb75b6ed58e 100644
--- a/docs/client-libraries-clients.md
+++ b/docs/client-libraries-clients.md
@@ -21,7 +21,7 @@ The following example creates a Python client using multiple
advertised listener
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
-
values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"}]}>
+
values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"Python","value":"Python"}]}>
<TabItem value="Java">
```java
@@ -31,6 +31,16 @@ The following example creates a Python client using multiple
advertised listener
.build();
```
+ </TabItem>
+ <TabItem value="C++">
+
+ ```cpp
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://xxxx:6650")
+ .listenerName("external")
+ .build();
+ ```
+
</TabItem>
<TabItem value="Python">
diff --git a/docs/client-libraries-producers.md
b/docs/client-libraries-producers.md
index 33af11c34f1..8a4aaa69181 100644
--- a/docs/client-libraries-producers.md
+++ b/docs/client-libraries-producers.md
@@ -18,7 +18,7 @@ This example shows how to create a producer.
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
@@ -29,6 +29,15 @@ Producer<String> producer =
pulsarClient.newProducer(Schema.STRING)
```
</TabItem>
+
+ <TabItem value="C++">
+
+ ```cpp
+ Producer producer;
+ Result result = client.createProducer("my-topic", producer);
+ ```
+
+ </TabItem>
</Tabs>
````
@@ -39,21 +48,32 @@ This example shows how to send messages using producers.
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
-
values={[{"label":"Java","value":"Java"},{"label":"Go","value":"Go"},{"label":"Node.js","value":"Node.js"},{"label":"C#","value":"C#"}]}>
+
values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"},{"label":"Node.js","value":"Node.js"},{"label":"C#","value":"C#"}]}>
<TabItem value="Java">
```java
producer.newMessage()
.key("my-message-key")
- .value("my-async-message")
- .property("my-key", "my-value")
- .property("my-other-key", "my-other-value")
+ .value("my-sync-message")
.send();
```
You can terminate the builder chain with `sendAsync()` and get a future
return.
</TabItem>
+
+ <TabItem value="C++">
+
+ ```cpp
+ Message msg = MessageBuilder()
+ .setContent("content")
+ .setPartitionKey("my-message-key")
+ .build();
+ Result res = producer.send(msg);
+ ```
+
+ </TabItem>
+
<TabItem value="Go">
```go
@@ -165,7 +185,33 @@ await producer.Send(data);
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="C#"
- values={[{"label":"C#","value":"C#"}]}>
+
values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"C#","value":"C#"}]}>
+
+ <TabItem value="Java">
+
+ ```java
+ producer.newMessage()
+ .value("my-sync-message")
+ .property("my-key", "my-value")
+ .property("my-other-key", "my-other-value")
+ .send();
+ ```
+
+ </TabItem>
+
+ <TabItem value="C++">
+
+ ```cpp
+ Message msg = MessageBuilder()
+ .setContent("content")
+ .setProperty("my-key", "my-value")
+ .setProperty("my-other-key", "my-other-value")
+ .build();
+ Result res = producer.send(msg);
+ ```
+
+ </TabItem>
+
<TabItem value="C#">
```csharp
@@ -178,25 +224,6 @@ await producer.Send(data);
</Tabs>
````
-- Send messages with customized metadata without using the builder.
-
- ````mdx-code-block
- <Tabs groupId="lang-choice"
- defaultValue="C#"
- values={[{"label":"C#","value":"C#"}]}>
- <TabItem value="C#">
-
- ```csharp
- var data = Encoding.UTF8.GetBytes("Hello World");
- var metadata = new MessageMetadata();
- metadata["SomeKey"] = "SomeValue";
- var messageId = await producer.Send(metadata, data));
- ```
-
- </TabItem>
- </Tabs>
- ````
-
## Async send messages
You can publish messages [asynchronously](concepts-clients.md#send-modes)
using the Java client. With async send, the producer puts the message in a
blocking queue and returns it immediately. Then the client library sends the
message to the broker in the background. If the queue is full (max size
configurable), the producer is blocked or fails immediately when calling the
API, depending on arguments passed to the producer.
@@ -206,7 +233,7 @@ The following is an example.
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
```java
@@ -216,6 +243,20 @@
producer.sendAsync("my-async-message".getBytes()).thenAccept(msgId -> {
```
</TabItem>
+
+<TabItem value="C++">
+
+```cpp
+Message msg = MessageBuilder()
+ .setContent("content")
+ .build();
+producer.sendAsync(msg, [](Result result, MessageId messageId) {
+ std::cout << "Result: " << result << "; Message ID:" << messageId;
+});
+```
+
+</TabItem>
+
</Tabs>
````
@@ -236,7 +277,7 @@ The following is an example:
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"},{"label":"Go","value":"Go"}]}>
+
values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"}]}>
<TabItem value="Java">
```java
@@ -252,6 +293,22 @@ The following is an example:
```
</TabItem>
+
+ <TabItem value="C++">
+
+ ```cpp
+ #include "lib/RoundRobinMessageRouter.h" // Make sure include this header
file
+
+ Producer producer;
+ Result result = client.createProducer(
+ "persistent://public/default/my-topic",
+
ProducerConfiguration().setMessageRouter(std::make_shared<RoundRobinMessageRouter>(
+ ProducerConfiguration::BoostHash, true, 1000, 100000,
boost::posix_time::seconds(1))),
+ producer);
+ ```
+
+ </TabItem>
+
<TabItem value="Go">
```go
@@ -317,18 +374,38 @@ The following is an example:
### Customize message router
-To use a custom message router, you need to provide an implementation of the
{@inject:
javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter}
interface, which has just one `choosePartition` method:
+
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
+To use a custom message router, you need to provide an implementation of the
{@inject:
javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter}
interface, which has just one `choosePartition` method:
+
```java
public interface MessageRouter extends Serializable {
int choosePartition(Message msg);
}
+```
+
+ </TabItem>
+
+ <TabItem value="C++">
+
+To use a custom message router, you need to provide an implementation of the
``MessageRoutingPolicy interface, which has just one `getPartition` method:
+
+```cpp
+class MessageRouter : public MessageRoutingPolicy {
+ public:
+ MessageRouter() : {}
+
+ int getPartition(const Message& msg, const TopicMetadata& topicMetadata) {
+ // The implementation of getPartition
+ }
+
+};
```
</TabItem>
@@ -340,7 +417,7 @@ The following router routes every message to partition 10:
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
```java
@@ -349,6 +426,20 @@ public class AlwaysTenRouter implements MessageRouter {
return 10;
}
}
+```
+
+ </TabItem>
+ <TabItem value="C++">
+
+```cpp
+class MessageRouter : public MessageRoutingPolicy {
+ public:
+ MessageRouter() {}
+
+ int getPartition(const Message& msg, const TopicMetadata& topicMetadata) {
+ return 10;
+ }
+};
```
</TabItem>
@@ -360,7 +451,7 @@ With that implementation, you can send messages to
partitioned topics as below.
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
```java
@@ -376,18 +467,27 @@ producer.send("Partitioned topic message".getBytes());
```
</TabItem>
+
+
+<TabItem value="C++">
+
+```cpp
+Producer producer;
+Result result = client.createProducer(
+ "persistent://public/default/my-topic",
+
ProducerConfiguration().setMessageRouter(std::make_shared<MessageRouter>()),
+ producer);
+Message msg = MessageBuilder().setContent("content").build();
+result = producer.send(msg);
+```
+
+ </TabItem>
</Tabs>
````
### Choose partitions when using a key
-If a message has a key, it supersedes the round robin routing policy. The
following example illustrates how to choose the partition when using a key.
-
-````mdx-code-block
-<Tabs groupId="lang-choice"
- defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
-<TabItem value="Java">
+If a message has a key, it supersedes the round robin routing policy. The
following java example code illustrates how to choose the partition when using
a key.
```java
// If the message has a key, it supersedes the round robin routing policy
@@ -403,10 +503,6 @@ If a message has a key, it supersedes the round robin
routing policy. The follow
}
```
- </TabItem>
-</Tabs>
-````
-
## Enable chunking
Message [chunking](concepts-messaging.md#chunking) enables Pulsar to process
large payload messages by splitting the message into chunks at the producer
side and aggregating chunked messages on the consumer side.
@@ -496,7 +592,7 @@ The following is an example of how to configure delayed
message delivery for a p
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"},{"label":"Go","value":"Go"}]}>
+
values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"}]}>
<TabItem value="Java">
```java
@@ -504,6 +600,16 @@ The following is an example of how to configure delayed
message delivery for a p
producer.newMessage().deliverAfter(3L, TimeUnit.Minute).value("Hello
Pulsar!").send();
```
+ </TabItem>
+ <TabItem value="C++">
+
+ ```cpp
+ Message msg = MessageBuilder().setContent("content")
+ .setDeliverAfter(std::chrono::minutes(3))
+ .build();
+ producer.send(msg);
+ ```
+
</TabItem>
<TabItem value="Go">
@@ -580,7 +686,7 @@ To intercept messages, you can add a `ProducerInterceptor`
or multiple ones when
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"C++","value":"C++"}]}>
<TabItem value="Java">
```java
@@ -606,6 +712,42 @@ To intercept messages, you can add a `ProducerInterceptor`
or multiple ones when
```
</TabItem>
+
+ <TabItem value="C++">
+ Implement the custom interceptor:
+
+ ```cpp
+ class MyInterceptor : public ProducerInterceptor {
+ public:
+ MyInterceptor() {}
+
+ Message beforeSend(const Producer& producer, const Message& message)
override {
+ // Your implementation code
+ return message;
+ }
+
+ void onSendAcknowledgement(const Producer& producer, Result result,
const Message& message,
+ const MessageId& messageID) override {
+ // Your implementation code
+ }
+
+ void close() override {
+ // Your implementation code
+ }
+ };
+ ```
+
+ Configue the producer:
+
+ ```cpp
+ ProducerConfiguration conf;
+ conf.intercept({std::make_shared<MyInterceptor>(),
+ std::make_shared<MyInterceptor>()}); // You can add
multiple interceptors to the same producer
+ Producer producer;
+ client.createProducer(topic, conf, producer);
+ ```
+
+ </TabItem>
</Tabs>
````
