This is an automated email from the ASF dual-hosted git repository.
mmerli 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 9c9d210 Add producer configuration description for Java client (#5154)
9c9d210 is described below
commit 9c9d2101d20fe86186b74ade461fcf45ed35f5ab
Author: Anonymitaet <50226895+anonymit...@users.noreply.github.com>
AuthorDate: Wed Sep 11 00:09:11 2019 +0800
Add producer configuration description for Java client (#5154)
---
site2/docs/client-libraries-java.md | 38 ++++++++++++++++++++++++++++---------
1 file changed, 29 insertions(+), 9 deletions(-)
diff --git a/site2/docs/client-libraries-java.md
b/site2/docs/client-libraries-java.md
index ccee7f9..68029a8 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -74,7 +74,7 @@ If you're using [TLS](security-tls-authentication.md)
authentication, the URL wi
pulsar+ssl://pulsar.us-west.example.com:6651
```
-## Client configuration
+## Client
You can instantiate a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
using just a URL for the target Pulsar
[cluster](reference-terminology.md#cluster), like this:
@@ -123,7 +123,7 @@ Check out the Javadoc for the {@inject:
javadoc:PulsarClient:/client/org/apache/
> In addition to client-level configuration, you can also apply
> [producer](#configuring-producers) and [consumer](#configuring-consumers)
> specific configuration, as you'll see in the sections below.
-## Producers
+## Producer
In Pulsar, producers write messages to topics. Once you've instantiated a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
(as in the section [above](#client-configuration)), you can create a {@inject:
javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific
Pulsar [topic](reference-terminology.md#topic).
@@ -162,9 +162,29 @@ stringProducer.send("My message");
> });
> ```
-### Configuring producers
+### Configure producer
-If you instantiate a `Producer` object specifying only a topic name, as in the
example above, the producer will use the default configuration. To use a
non-default configuration, there's a variety of configurable parameters that
you can set.
+If you instantiate a `Producer` object specifying only a topic name, as in the
example above, the producer uses the default configuration.
+
+If you create a producer, you may use the `loadConf` configuration. Below are
the available parameters used in `loadConf`.
+
+Type | Name| <div style="width:300px">Description</div>| Default
+|---|---|---|---
+String| `topicName`| Topic name| null|
+String|`producerName`|Producer name| null
+long|`sendTimeoutMs`|Message send timeout in ms.<br/><br/>If a message is not
acknowledged by a server before the `sendTimeout` expires, an error is
triggered.|30000
+boolean|`blockIfQueueFull`|If set to `true`, when the outgoing message queue
is full, the `Send` and `SendAsync` methods of producer block rather than
failing and throwing errors. <br/><br>If set to `false`, when the outgoing
message queue is full, the `Send` and `SendAsync` methods of producer fail and
throw `ProducerQueueIsFullError` exceptions.<br/><br/>The size of the outgoing
message queue is determined by the `MaxPendingMessages` parameter.|false
+int|`maxPendingMessages`|Maximum size of a queue holding pending
messages.<br/><br/>For example, a message waiting to receive an acknowledgment
from a [broker](reference-terminology.md#broker). <br/><br/>By default, when
the queue is full, all calls to the `Send` and `SendAsync` methods fail
**unless** `BlockIfQueueFull` is set to `true`.|1000
+int|`maxPendingMessagesAcrossPartitions`|Maximum number of pending messages
across partitions. <br/><br/>This setting is used to lower the max pending
messages for each partition ({@link #setMaxPendingMessages(int)}) if the total
exceeds the configured value.|50000
+MessageRoutingMode|`messageRoutingMode`|Message routing logic for producers on
[partitioned
topics](concepts-architecture-overview.md#partitioned-topics).<br/><br/> This
logic is applied only when no key is set on messages. <br/><br/>Below are the
available options: <br/><br/><li>`pulsar.RoundRobinDistribution`: round
robin<br/><br/> <li>`pulsar.UseSinglePartition`: publish all messages to a
single partition<br/><br/><li>`pulsar.CustomPartition`: a custom partitioning
scheme|`pulsar.Roun [...]
+HashingScheme|`hashingScheme`|Hashing function that determines the partition
on which a particular message is published (**partitioned topics
only**).<br/><br/>Below are the available options:<br/><br/><li>
`pulsar.JavaStringHash`: the equivalent of `String.hashCode()` in
Java<br/><br/><li> `pulsar.Murmur3_32Hash`: applies the
[Murmur3](https://en.wikipedia.org/wiki/MurmurHash) hashing
function<br/><br/><li>`pulsar.BoostHash`: applies the hashing function from
C++'s [Boost](https://www.b [...]
+ProducerCryptoFailureAction|`cryptoFailureAction`|Producer should take action
when encryption fails.<br/><br/><li>**FAIL**: if encryption fails, unencrypted
messages fail to send.</li><br/><li> **SEND**: if encryption fails, unencrypted
messages are sent. |`ProducerCryptoFailureAction.FAIL`
+long|`batchingMaxPublishDelayMicros`|Time period within which messages sent
will be batched.|TimeUnit.MILLISECONDS.toMicros(1)
+int|batchingMaxMessages|Maximum number of messages permitted in a batch.|1000
+boolean|`batchingEnabled`|Enable batching of messages. |true
+CompressionType|`compressionType`|Message data compression type used by a
producer. <br/><br/>Below are the available
options:<li>[`LZ4`](https://github.com/lz4/lz4)<br/><li>[`ZLIB`](https://zlib.net/)<br/><li>[`ZSTD`](https://facebook.github.io/zstd/)<br/><li>[`SNAPPY`](https://google.github.io/snappy/)|
No compression
+
+To use a non-default configuration, there's a variety of configurable
parameters that you can set.
For a full listing, see the Javadoc for the {@inject:
javadoc:ProducerBuilder:/client/org/apache/pulsar/client/api/ProducerBuilder}
class. Here's an example:
@@ -195,7 +215,7 @@
producer.sendAsync("my-async-message".getBytes()).thenAccept(msgId -> {
As you can see from the example above, async send operations return a
{@inject: javadoc:MessageId:/client/org/apache/pulsar/client/api/MessageId}
wrapped in a
[`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
-### Configuring messages
+### Configure messages
In addition to a value, it's possible to set additional items on a given
message:
@@ -211,7 +231,7 @@ producer.newMessage()
As for the previous case, it's also possible to terminate the builder chain
with `sendAsync()` and
get a future returned.
-## Consumers
+## 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)).
@@ -245,7 +265,7 @@ while (true) {
}
```
-### Configuring consumers
+### Configure consumer
If you instantiate a `Consumer` object specifying only a topic and
subscription name, as in the example above, the consumer will use the default
configuration.
@@ -551,7 +571,7 @@ consumer 2 will receive:
>
> If the message key is not specified, messages without key will be dispatched
> to one consumer in order by default.
-## Reader interface
+## Reader
With the [reader interface](concepts-clients.md#reader-interface), Pulsar
clients can "manually position" themselves within a topic, reading all messages
from a specified message onward. The Pulsar API for Java enables you to create
{@inject: javadoc:Reader:/client/org/apache/pulsar/client/api/Reader} objects
by specifying a topic, a {@inject:
javadoc:MessageId:/client/org/apache/pulsar/client/api/MessageId}, and
{@inject: javadoc:ReaderConfiguration:/client/org/apache/pulsar/client/api [...]
@@ -576,7 +596,7 @@ In the example above, a `Reader` object is instantiated for
a specific topic and
The code sample above shows pointing the `Reader` object to a specific message
(by ID), but you can also use `MessageId.earliest` to point to the earliest
available message on the topic of `MessageId.latest` to point to the most
recent available message.
-## Schemas
+## Schema
In Pulsar, all message data consists of byte arrays "under the hood." [Message
schemas](concepts-schema-registry.md) 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:
