This is an automated email from the ASF dual-hosted git repository. sijie pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git
The following commit(s) were added to refs/heads/master by this push: new f05c73b Fixes to new Java API intro docs (#1860) f05c73b is described below commit f05c73bbd59d7398bf69ecb0d259924a8c250f78 Author: Matteo Merli <mme...@apache.org> AuthorDate: Wed May 30 09:54:30 2018 -0700 Fixes to new Java API intro docs (#1860) --- site/docs/latest/clients/Java.md | 89 +++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 46 deletions(-) diff --git a/site/docs/latest/clients/Java.md b/site/docs/latest/clients/Java.md index 9931492..915adb1 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(); ``` -- To stop receiving notification emails like this one, please contact si...@apache.org.