asafm commented on code in PR #393:
URL: https://github.com/apache/pulsar-site/pull/393#discussion_r1098641042
##########
docs/client-libraries-java.md:
##########
@@ -4,1316 +4,37 @@ title: Pulsar Java client
sidebar_label: "Java"
---
-````mdx-code-block
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-````
+You can use a Pulsar Java client to create Pulsar producers, consumers, and
readers in Java and perform [administrative tasks](admin-api-overview.md). All
the methods in Java clients are thread-safe. The current Java client version is
**@pulsar:version@**.
Review Comment:
Let's add hyperlinks to what is Producer, Consumer and Reader (should be in
concept pages).
##########
docs/client-libraries-java-use.md:
##########
@@ -0,0 +1,123 @@
+---
+id: client-libraries-java-use
+title: Use a Java client
+sidebar_label: "Use"
+---
+
+## Create a producer
+
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific
Pulsar [topic](reference-terminology.md#topic).
+
+```java
+Producer<byte[]> producer = client.newProducer()
+ .topic("my-topic")
+ .create();
+
+// You can then send messages to the broker and topic you specified:
+producer.send("My message".getBytes());
+```
+
+By default, producers produce messages that consist of byte arrays. You can
produce different types by specifying a message [schema](#schema).
+
+```java
+Producer<String> stringProducer = client.newProducer(Schema.STRING)
+ .topic("my-topic")
+ .create();
+stringProducer.send("My message");
+```
+
+> Make sure that you close your producers, consumers, and clients when you do
not need them.
+
+> ```java
+> producer.close();
+> consumer.close();
+> client.close();
+> ```
+
+>
+> Close operations can also be asynchronous:
+
+> ```java
+> producer.closeAsync()
+> .thenRun(() -> System.out.println("Producer closed"))
+> .exceptionally((ex) -> {
+> System.err.println("Failed to close producer: " + ex);
+> return null;
+> });
+> ```
+
+## Create a consumer
+
+In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
+
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Consumer:/client/org/apache/pulsar/client/api/Consumer} by specifying a
[topic](reference-terminology.md#topic) and a
[subscription](concepts-messaging.md#subscription-types).
+
+```java
+Consumer consumer = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscribe();
+```
+
+The `subscribe` method will auto-subscribe the consumer to the specified topic
and subscription. One way to make the consumer listen to the topic is to set up
a `while` loop. In this example loop, the consumer listens for messages, prints
the contents of any received message, and then
[acknowledges](reference-terminology.md#acknowledgment-ack) that the message
has been processed. If the processing logic fails, you can use [negative
acknowledgment](reference-terminology.md#acknowledgment-ack) to redeliver the
message later.
+
+```java
+while (true) {
+ // Wait for a message
+ Message msg = consumer.receive();
+
+ try {
+ // Do something with the message
+ System.out.println("Message received: " + new String(msg.getData()));
+
+ // Acknowledge the message so that it can be deleted by the message
broker
+ consumer.acknowledge(msg);
+ } catch (Exception e) {
+ // Message failed to process, redeliver later
+ consumer.negativeAcknowledge(msg);
+ }
+}
+```
+
+If you don't want to block your main thread and rather listen constantly for
new messages, consider using a `MessageListener`.
Review Comment:
Well, you're blocking something. Perhaps clarify which other thread is doing
the work, how work is divided there, or link to an advanced page to explain
that?
##########
docs/client-libraries-java-use.md:
##########
@@ -0,0 +1,123 @@
+---
+id: client-libraries-java-use
+title: Use a Java client
+sidebar_label: "Use"
+---
+
+## Create a producer
+
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific
Pulsar [topic](reference-terminology.md#topic).
+
+```java
+Producer<byte[]> producer = client.newProducer()
+ .topic("my-topic")
+ .create();
+
+// You can then send messages to the broker and topic you specified:
+producer.send("My message".getBytes());
+```
+
+By default, producers produce messages that consist of byte arrays. You can
produce different types by specifying a message [schema](#schema).
+
+```java
+Producer<String> stringProducer = client.newProducer(Schema.STRING)
+ .topic("my-topic")
+ .create();
+stringProducer.send("My message");
+```
+
+> Make sure that you close your producers, consumers, and clients when you do
not need them.
+
+> ```java
+> producer.close();
+> consumer.close();
+> client.close();
+> ```
+
+>
+> Close operations can also be asynchronous:
+
+> ```java
+> producer.closeAsync()
+> .thenRun(() -> System.out.println("Producer closed"))
+> .exceptionally((ex) -> {
+> System.err.println("Failed to close producer: " + ex);
+> return null;
+> });
+> ```
+
+## Create a consumer
+
+In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
Review Comment:
Acknowledgment basic template should look different based on type of
subscription and if topic is partitioned or not.
If subscription is exclusive, the developer should use cumulative
acknowledgment.
If subscription is exclusive, and topic is partitioned topic, there should
be special code pattern to do cumulative ACK per partition.
I think it was @BewareMyPower or @tisonkun talking about it in the mailing
list.
For sure it should be in this page.
##########
docs/client-libraries-java-use.md:
##########
@@ -0,0 +1,123 @@
+---
+id: client-libraries-java-use
+title: Use a Java client
+sidebar_label: "Use"
+---
+
+## Create a producer
+
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific
Pulsar [topic](reference-terminology.md#topic).
+
+```java
+Producer<byte[]> producer = client.newProducer()
+ .topic("my-topic")
+ .create();
+
+// You can then send messages to the broker and topic you specified:
+producer.send("My message".getBytes());
+```
+
+By default, producers produce messages that consist of byte arrays. You can
produce different types by specifying a message [schema](#schema).
+
+```java
+Producer<String> stringProducer = client.newProducer(Schema.STRING)
+ .topic("my-topic")
+ .create();
+stringProducer.send("My message");
+```
+
+> Make sure that you close your producers, consumers, and clients when you do
not need them.
+
+> ```java
+> producer.close();
+> consumer.close();
+> client.close();
+> ```
+
+>
+> Close operations can also be asynchronous:
+
+> ```java
+> producer.closeAsync()
+> .thenRun(() -> System.out.println("Producer closed"))
+> .exceptionally((ex) -> {
+> System.err.println("Failed to close producer: " + ex);
+> return null;
+> });
+> ```
+
+## Create a consumer
+
+In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
+
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Consumer:/client/org/apache/pulsar/client/api/Consumer} by specifying a
[topic](reference-terminology.md#topic) and a
[subscription](concepts-messaging.md#subscription-types).
+
+```java
+Consumer consumer = client.newConsumer()
+ .topic("my-topic")
+ .subscriptionName("my-subscription")
+ .subscribe();
+```
+
+The `subscribe` method will auto-subscribe the consumer to the specified topic
and subscription. One way to make the consumer listen to the topic is to set up
a `while` loop. In this example loop, the consumer listens for messages, prints
the contents of any received message, and then
[acknowledges](reference-terminology.md#acknowledgment-ack) that the message
has been processed. If the processing logic fails, you can use [negative
acknowledgment](reference-terminology.md#acknowledgment-ack) to redeliver the
message later.
+
+```java
+while (true) {
+ // Wait for a message
+ Message msg = consumer.receive();
+
+ try {
+ // Do something with the message
+ System.out.println("Message received: " + new String(msg.getData()));
+
+ // Acknowledge the message so that it can be deleted by the message
broker
Review Comment:
It won't delete necessarily - maybe clarify and hyperlink to where to
understand what it is ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
