[GitHub] sijie closed pull request #1860: Fixes to new Java API intro docs

[GitBox <gi...@apache.org>]

sijie closed pull request #1860: Fixes to new Java API intro docs
URL: https://github.com/apache/incubator-pulsar/pull/1860
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/site/docs/latest/clients/Java.md b/site/docs/latest/clients/Java.md
index 9931492faf..915adb195e 100644
--- a/site/docs/latest/clients/Java.md
+++ b/site/docs/latest/clients/Java.md
@@ -76,9 +76,8 @@ dependencies {
 You can instantiate a {% javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object using just a URL for the target Pulsar {% popover cluster %}, like this:
 
 ```java
-String pulsarBrokerRootUrl = "pulsar://localhost:6650";
 PulsarClient client = PulsarClient.builder()
-        .serviceUrl(pulsarBrokerRootUrl)
+        .serviceUrl("pulsar://localhost:6650")
         .build();
 ```
 
@@ -96,40 +95,21 @@ In addition to client-level configuration, you can also apply [producer](#config
 In Pulsar, {% popover producers %} write {% popover messages %} to {% popover topics %}. Once you've instantiated a {% javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object (as in the section [above](#client-configuration)), you can create a {% javadoc Producer client org.apache.pulsar.client.api.Producer %} for a specific Pulsar {% popover topic %}.
 
 ```java
-String topic = "persistent://public/default/my-topic";
-
 Producer<byte[]> producer = client.newProducer()
-        .topic(topic)
+        .topic("my-topic")
         .create();
-```
-
-You can then send messages to the broker and topic you specified:
-
-```java
-import org.apache.pulsar.client.api.TypedMessageBuilder;
-
-import java.util.stream.IntStream;
-
-TypedMessageBuilder<byte[]> msgBuilder = producer.newMessage();
 
-// Publish 10 messages to the topic
-IntStream.range(1, 11).forEach(i -> {
-    msgBuilder.value(String.format("Message number %d", i).getBytes());
-
-    try {
-        msgBuilder.send();
-    } catch (PulsarClientException e) {
-        e.printStackTrace();
-    }
-});
+// 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, however, by specifying a message [schema](#schemas).
 
 ```java
-Producer<String> stringProducer = client.newProducer(new StringSchema())
-        .topic(topic)
+Producer<String> stringProducer = client.newProducer(Schema.STRING)
+        .topic("my-topic")
         .create();
+stringProducer.send("My message");
 ```
 
 {% include admonition.html type='warning' content='
@@ -144,7 +124,12 @@ client.close();
 Close operations can also be asynchronous:
 
 ```java
-producer.closeAsync().thenRun(() -> System.out.println("Producer closed"));
+producer.closeAsync()
+    .thenRun(() -> System.out.println("Producer closed"));
+    .exceptionally((ex) -> {
+        System.err.println("Failed to close producer: " + ex);
+        return ex;
+    });
 ```
 ' %}
 
@@ -154,11 +139,11 @@ If you instantiate a `Producer` object specifying only a topic name, as in the e
 
 ```java
 Producer<byte[]> producer = client.newProducer()
-        .topic(topic)
-        .enableBatching(true)
-        .sendTimeout(10, TimeUnit.SECONDS)
-        .producerName("my-producer")
-        .create();
+    .topic("my-topic")
+    .batchingMaxPublishDelay(10, TimeUnit.MILLISECONDS)
+    .sendTimeout(10, TimeUnit.SECONDS)
+    .blockIfQueueFull(true)
+    .create();
 ```
 
 ### Message routing
@@ -172,17 +157,29 @@ You can also publish messages [asynchronously](../../getting-started/ConceptsAnd
 Here's an example async send operation:
 
 ```java
-TypedMessageBuilder<byte[]> msgBuilder = producer.newMessage()
-        .value("my-async-message".getBytes());
-
-CompletableFuture<MessageId> future = msgBuilder.sendAsync();
-future.thenAccept(msgId -> {
-        System.out.printf("Message with ID %s successfully sent", new String(msgId.toByteArray());
+producer.sendAsync("my-async-message".getBytes()).thenAccept(msgId -> {
+    System.out.printf("Message with ID %s successfully sent", msgId);
 });
 ```
 
 As you can see from the example above, async send operations return a {% javadoc MessageId client org.apache.pulsar.client.api.MessageId %} wrapped in a [`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
 
+### Configuring messages
+
+In addition to a value, it's possible to set additional items on a given message:
+
+```java
+producer.newMessage()
+    .key("my-message-key")
+    .value("my-async-message".getBytes())
+    .property("my-key", "my-value")
+    .property("my-other-key", "my-other-value")
+    .send();
+```
+
+As for the previous case, it's also possible to terminate the builder chain with `sendAsync()` and
+get a future returned.
+
 ## Consumers
 
 In Pulsar, {% popover consumers %} subscribe to {% popover topics %} and handle {% popover messages %} that {% popover producers %} publish to those topics. You can instantiate a new {% popover consumer %} by first instantiating a {% javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object and passing it a URL for a Pulsar {% popover broker %} (as [above](#client-configuration)).
@@ -271,9 +268,9 @@ You can also subscribe to an explicit list of topics (across namespaces if you w
 
 ```java
 List<String> topics = Arrays.asList(
-        "persistent://public/default/topic-1",
-        "persistent://public/default/topic-2",
-        "persistent://public/default/topic-3"
+        "topic-1",
+        "topic-2",
+        "topic-3"
 );
 
 Consumer multiTopicConsumer = consumerBuilder
@@ -283,9 +280,9 @@ Consumer multiTopicConsumer = consumerBuilder
 // Alternatively:
 Consumer multiTopicConsumer = consumerBuilder
         .topics(
-            "persistent://public/default/topic-1",
-            "persistent://public/default/topic-2",
-            "persistent://public/default/topic-3"
+            "topic-1",
+            "topic-2",
+            "topic-3"
         )
         .subscribe();
 ```
@@ -339,7 +336,7 @@ The code sample above shows pointing the `Reader` object to a specific message (
 In Pulsar, all message data consists of byte arrays "under the hood." [Message schemas](../../getting-started/ConceptsAndArchitecture#schema-registry) enable you to use other types of data when constructing and handling messages (from simple types like strings to more complex, application-specific types). If you construct, say, a [producer](#producers) without specifying a schema, then the producer can only produce messages of type `byte[]`. Here's an example:
 
 ```java
-Producer producer = client.newProducer()
+Producer<byte[]> producer = client.newProducer()
         .topic(topic)
         .create();
 ```


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services