Package org.apache.pulsar.reactive.client.api

Interface ReactiveMessageSenderBuilder<T>

Type Parameters:
T - the message payload type
public interface ReactiveMessageSenderBuilder<T>
Builder interface for ReactiveMessageSender.

  • Method Details

    • cache

      ReactiveMessageSenderBuilder<T> cache(ReactiveMessageSenderCache producerCache)
      Sets the cache to use for the sender.
      Parameters:
      producerCache - the cache to set
      Returns:
      the sender builder instance

    • maxInflight

      ReactiveMessageSenderBuilder<T> maxInflight(int maxInflight)
      Sets the maximum number of in-flight messages for the sender. When this value is reached, backpressure will be triggered on the ReactiveMessageSender.sendOne(MessageSpec)/ReactiveMessageSender.sendMany(Publisher) operations. Note that the maxInflight setting applies globally for all the operations called on the sender.
      Parameters:
      maxInflight - the maximum number of in-flight messages for the sender.
      Returns:
      the sender builder instance

    • maxConcurrentSenderSubscriptions

      ReactiveMessageSenderBuilder<T> maxConcurrentSenderSubscriptions(int maxConcurrentSenderSubscriptions)
      Sets the maximum number of concurrent subscriptions for the sender. Note that the maxConcurrentSenderSubscriptions setting applies globally for all the operations called on the sender.
      Parameters:
      maxConcurrentSenderSubscriptions - the maximum number of concurrent subscriptions for the sender.
      Returns:
      the sender builder instance

    • stopOnError

      ReactiveMessageSenderBuilder<T> stopOnError(boolean stopOnError)
      Sets whether an error when sending an individual message of the ReactiveMessageSender.sendMany(Publisher) operation should stop the full stream or not. (default: false). If true, the original error is wrapped in a ReactiveMessageSendingException and propagated downstream. If false, a MessageSendResult is returned with the exception put in the Exception field and a null MessageId field.
      Parameters:
      stopOnError - true if the send stream should stop on error, false otherwise.
      Returns:
      the sender builder instance

    • clone

      ReactiveMessageSenderBuilder<T> clone()
      Creates and returns a copy of this reactive sender builder.
      Returns:
      the cloned reactive reader builder

    • applySpec

      default ReactiveMessageSenderBuilder<T> applySpec(ReactiveMessageSenderSpec senderSpec)
      Applies a sender spec to configure the sender.
      Parameters:
      senderSpec - the sender spec to apply
      Returns:
      the sender builder instance

    • toImmutableSpec

      default ReactiveMessageSenderSpec toImmutableSpec()
      Converts this builder to an immutable reactive sender spec with the same settings.
      Returns:
      the reactive sender spec.

    • getMutableSpec

      MutableReactiveMessageSenderSpec getMutableSpec()
      Converts this builder to a mutable reactive sender spec with the same settings.
      Returns:
      the reactive sender spec.

    • topic

      default ReactiveMessageSenderBuilder<T> topic(String topicName)
      Sets the topic this sender will be publishing on.

      This argument is required when constructing the sender.

      Parameters:
      topicName - the name of the topic
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.topic(String)

    • producerName

      default ReactiveMessageSenderBuilder<T> producerName(String producerName)
      Sets a name for the producers created under this sender.

      If not assigned, the system will generate a globally unique name to each producer.

      Warning: When specifying a name, it is up to the user to ensure that, for a given topic, the producer name is unique across all Pulsar's clusters. Brokers will enforce that only a single producer given name can be publishing on a topic.

      Parameters:
      producerName - the name to use for the producer
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.producerName(String)

    • sendTimeout

      default ReactiveMessageSenderBuilder<T> sendTimeout(Duration sendTimeout)
      Sets the send timeout (default: 30 seconds) for this sender.

      If a message is not acknowledged by the server before the sendTimeout expires, an error will be reported.

      Setting the timeout to zero, for example setTimeout(Duration.ZERO) will set the timeout to infinity, which can be useful when using Pulsar's message deduplication feature, since the client library will retry forever to publish a message. No errors will be propagated back to the application.

      Parameters:
      sendTimeout - the send timeout to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.sendTimeout(int, TimeUnit)

    • maxPendingMessages

      default ReactiveMessageSenderBuilder<T> maxPendingMessages(int maxPendingMessages)
      Sets the maximum size of the queues holding the messages pending to receive an acknowledgment from the broker. This setting applies to each producer created under this sender.

      The producer queue size also determines the max amount of memory that will be required by the client application. Until the producer gets a successful acknowledgment back from the broker, it will keep in memory (direct memory pool) all the messages in the pending queue.

      Default is 0, disable the pending messages check.

      Parameters:
      maxPendingMessages - the maximum size of the pending messages queue for the sender to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.maxPendingMessages(int)

    • maxPendingMessagesAcrossPartitions

      default ReactiveMessageSenderBuilder<T> maxPendingMessagesAcrossPartitions(int maxPendingMessagesAcrossPartitions)
      Sets the maximum number of pending messages across all the partitions. This setting applies to each producer created under this sender.

      This setting will be used to lower the max pending messages for each partition (maxPendingMessages(int)), if the total exceeds the configured value. The purpose of this setting is to have an upper-limit on the number of pending messages when publishing on a partitioned topic.

      Default is 0, disable the pending messages across partitions check.

      If publishing at high rate over a topic with many partitions (especially when publishing messages without a partitioning key), it might be beneficial to increase this parameter to allow for more pipelining within the individual partitions senders.

      Parameters:
      maxPendingMessagesAcrossPartitions - the maximum number of pending messages across all the partitions to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.maxPendingMessagesAcrossPartitions(int)

    • messageRoutingMode

      default ReactiveMessageSenderBuilder<T> messageRoutingMode(org.apache.pulsar.client.api.MessageRoutingMode messageRoutingMode)
      Sets the routing mode for a partitioned producer. This setting applies to each producer created under this sender.

      The default routing mode is to round-robin across the available partitions.

      This logic is applied when the application is not setting a key on a particular message. If the key is set with MessageSpecBuilder.key(String), then the hash of the key will be used to select a partition for the message.

      Parameters:
      messageRoutingMode - the message routing mode to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.messageRoutingMode(MessageRoutingMode)

    • hashingScheme

      default ReactiveMessageSenderBuilder<T> hashingScheme(org.apache.pulsar.client.api.HashingScheme hashingScheme)
      Sets the hashing scheme used to choose the partition on where to publish a particular message.

      Standard hashing functions available are:

      Parameters:
      hashingScheme - the hashing scheme to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.hashingScheme(HashingScheme)

    • cryptoFailureAction

      default ReactiveMessageSenderBuilder<T> cryptoFailureAction(org.apache.pulsar.client.api.ProducerCryptoFailureAction cryptoFailureAction)
      Sets the action the sender will take in case of encryption failures.
      Parameters:
      cryptoFailureAction - the action the sender will take in case of encryption failures to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.cryptoFailureAction(ProducerCryptoFailureAction)

    • messageRouter

      default ReactiveMessageSenderBuilder<T> messageRouter(org.apache.pulsar.client.api.MessageRouter messageRouter)
      Sets a custom message routing policy by passing an implementation of MessageRouter.
      Parameters:
      messageRouter - the message router to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.messageRouter(MessageRouter)

    • batchingMaxPublishDelay

      default ReactiveMessageSenderBuilder<T> batchingMaxPublishDelay(Duration batchingMaxPublishDelay)
      Sets the time period within which the messages sent will be batched default: 1 ms if batched messages are enabled. If set to a non-zero value, messages will be queued until either:

      All messages will be published as a single batch message. The consumer will be delivered individual messages in the batch in the same order they were enqueued.

      Parameters:
      batchingMaxPublishDelay - the time period within which the messages sent will be batched
      Returns:
      the sender builder instance
      See Also:

    • roundRobinRouterBatchingPartitionSwitchFrequency

      default ReactiveMessageSenderBuilder<T> roundRobinRouterBatchingPartitionSwitchFrequency(int roundRobinRouterBatchingPartitionSwitchFrequency)
      Sets the partition switch frequency while batching of messages is enabled and using round-robin routing mode for non-keyed message default: 10.

      The time period of partition switch is roundRobinRouterBatchingPartitionSwitchFrequency * batchingMaxPublishDelay(java.time.Duration). During this period, all messages that arrive will be routed to the same partition.

      Parameters:
      roundRobinRouterBatchingPartitionSwitchFrequency - the frequency of partition switch
      Returns:
      the sender builder instance
      See Also:

    • batchingMaxMessages

      default ReactiveMessageSenderBuilder<T> batchingMaxMessages(int batchingMaxMessages)
      Sets the maximum number of messages permitted in a batch. default: 1000 If set to a value greater than 1, messages will be batched until this threshold or the maximum byte size of a batch is reached or the batch publish delay has elapsed.

      All messages in a batch will be published as a single batch message. The consumer will be delivered individual messages in the batch in the same order they were enqueued.

      Parameters:
      batchingMaxMessages - the maximum number of messages in a batch to set
      Returns:
      the sender builder instance
      See Also:

    • batchingMaxBytes

      default ReactiveMessageSenderBuilder<T> batchingMaxBytes(int batchingMaxBytes)
      Sets the maximum number of bytes permitted in a batch. default: 128KB If set to a value greater than 0, messages will be queued until this threshold is reached or other batching conditions are met.

      All messages in a batch will be published as a single batched message. The consumer will be delivered individual messages in the batch in the same order they were enqueued.

      Parameters:
      batchingMaxBytes - the maximum number of bytes in a batch to set
      Returns:
      the sender builder instance
      See Also:

    • batchingEnabled

      default ReactiveMessageSenderBuilder<T> batchingEnabled(boolean batchingEnabled)
      Sets whether batching of messages is enabled for the sender. default: enabled

      When batching is enabled, multiple calls to ReactiveMessageSender.sendOne(MessageSpec)/ReactiveMessageSender.sendMany(Publisher) may result in a single batch to be sent to the broker, leading to better throughput, especially when publishing small messages. If compression is enabled, messages will be compressed at the batch level, leading to a much better compression ratio for similar headers or contents.

      When enabled default batch delay is set to 1 ms and default batch size is 1000 messages

      Batching is enabled by default since 2.0.0.

      Parameters:
      batchingEnabled - whether batching is enabled
      Returns:
      the sender builder instance
      See Also:

    • batcherBuilder

      default ReactiveMessageSenderBuilder<T> batcherBuilder(org.apache.pulsar.client.api.BatcherBuilder batcherBuilder)
      Sets the batcher builder of the sender. The sender will use the batcher builder to build a batch message container.This is only used when batching is enabled.
      Parameters:
      batcherBuilder - the batcher builder to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.batcherBuilder(BatcherBuilder)

    • chunkingEnabled

      default ReactiveMessageSenderBuilder<T> chunkingEnabled(boolean chunkingEnabled)
      Sets whether chunking of messages is enabled If enabled, when the message size is higher than the maximum allowed publishing payload size on the broker, then the sender will split the message into multiple chunks and publish them to the broker separately and in order. The consumer will stitch them together to form the original published message.This allows clients to publish large messages.

      Recommendations to use this feature: 

       1. Chunking is only supported by non-shared subscriptions and persistent-topic.
 2. Batching shouldn't be used together with chunking.
 3. The ReactivePulsarClient keeps published messages into a buffer until it receives the acknowledgements from the broker.
 So, it's better to reduce the maxPendingMessages(int) size to prevent the sender occupying large amount
  of memory from these buffered messages.
 4. Set the message TTL on the namespace to cleanup incomplete chunked messages.
 (sometimes, due to broker-restart or publish timeout, the sender might fail to publish an entire large message.
 So the consumer will not be able to consume and acknowledge those messages. So, those messages can
 only be discarded by message TTL) Or configure
 ReactiveMessageConsumerBuilder.expireTimeOfIncompleteChunkedMessage(java.time.Duration)
 5. Consumer configuration: the consumer should also configure ReactiveMessageConsumerBuilder.receiverQueueSize(java.lang.Integer) and ReactiveMessageConsumerBuilder.maxPendingChunkedMessage(java.lang.Integer)
      Parameters:
      chunkingEnabled - whether to enable chunking
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.enableChunking(boolean)

    • cryptoKeyReader

      default ReactiveMessageSenderBuilder<T> cryptoKeyReader(org.apache.pulsar.client.api.CryptoKeyReader cryptoKeyReader)
      Sets the key reader to be used to encrypt the message payloads.
      Parameters:
      cryptoKeyReader - the key reader to be used to encrypt the message payloads.
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.cryptoKeyReader(CryptoKeyReader)

    • encryptionKeys

      default ReactiveMessageSenderBuilder<T> encryptionKeys(Set<String> encryptionKeys)
      Sets the public encryption key names, used by the producer to encrypt the data key.

      At the time of producer creation, the Pulsar client checks if there are keys added to encryptionKeys. If keys are found, a callback CryptoKeyReader.getPrivateKey(String, Map) and CryptoKeyReader.getPublicKey(String, Map) is invoked against each key to load the values of the key. Applications should implement this callback to return the key in pkcs8 format. If compression is enabled, the message is encrypted after compression. If batch messaging is enabled, the batched message is encrypted.

      Parameters:
      encryptionKeys - the names of the encryption keys in the key store
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.addEncryptionKey(String)

    • compressionType

      default ReactiveMessageSenderBuilder<T> compressionType(org.apache.pulsar.client.api.CompressionType compressionType)
      Sets the compression type for the sender.

      By default, message payloads are not compressed. Supported compression types are:

      • CompressionType.NONE: No compression (Default)
      • CompressionType.LZ4: Compress with LZ4 algorithm. Faster but lower compression than ZLib
      • CompressionType.ZLIB: Standard ZLib compression
      • CompressionType.ZSTD: Compress with Zstandard codec. Since Pulsar 2.3. Zstd cannot be used if consumer applications are not in version >= 2.3 as well
      • CompressionType.SNAPPY Compress with Snappy codec. Since Pulsar 2.4. Snappy cannot be used if consumer applications are not in version >= 2.4 as well
      Parameters:
      compressionType - the compression type to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.compressionType(CompressionType)

    • initialSequenceId

      default ReactiveMessageSenderBuilder<T> initialSequenceId(long initialSequenceId)
      Sets the baseline for the sequence ids for messages published by the producer. This setting applies to each producer created under this sender.

      First message will be using (initialSequenceId + 1) as its sequence id and subsequent messages will be assigned incremental sequence ids, if not otherwise specified.

      Parameters:
      initialSequenceId - the initial sequence id for the producer to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.initialSequenceId(long)

    • autoUpdatePartitions

      default ReactiveMessageSenderBuilder<T> autoUpdatePartitions(boolean autoUpdatePartitions)
      If enabled, the sender will automatically discover new partitions of partitioned topics at runtime.

      Default is true.

      Parameters:
      autoUpdatePartitions - whether to auto discover the partition configuration changes
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.autoUpdatePartitions(boolean)

    • autoUpdatePartitionsInterval

      default ReactiveMessageSenderBuilder<T> autoUpdatePartitionsInterval(Duration autoUpdatePartitionsInterval)
      Sets the interval of partitions updates (default: 1 minute). This only works if autoUpdatePartitions(boolean) is enabled.
      Parameters:
      autoUpdatePartitionsInterval - the interval of partitions updates
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.autoUpdatePartitionsInterval(int, TimeUnit)

    • multiSchema

      default ReactiveMessageSenderBuilder<T> multiSchema(boolean multiSchema)
      Sets whether to enable the multiple schema mode for the producer. If enabled, the producer can send a message with a different schema from the one specified when it was created, otherwise an invalid message exception would be thrown.

      Enabled by default.

      Parameters:
      multiSchema - whether to enable or disable multiple schema mode
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.enableMultiSchema(boolean)

    • accessMode

      default ReactiveMessageSenderBuilder<T> accessMode(org.apache.pulsar.client.api.ProducerAccessMode accessMode)
      Sets the type of access mode that the producer requires on the topic. This setting applies to each producer created under this sender.

      Possible values are:

      • ProducerAccessMode.Shared: By default multiple producers can publish on a topic
      • ProducerAccessMode.Exclusive: Require exclusive access for producer. Fail immediately if there's already a producer connected.
      • ProducerAccessMode.WaitForExclusive: Producer creation is pending until it can acquire exclusive access
      Parameters:
      accessMode - the access mode to set
      Returns:
      the producer builder instance
      See Also:
      • ProducerBuilder.accessMode(ProducerAccessMode)

    • lazyStartPartitionedProducers

      default ReactiveMessageSenderBuilder<T> lazyStartPartitionedProducers(boolean lazyStartPartitionedProducers)
      Sets whether to start partitioned producers lazily. This setting applies to each producer created under this sender. This config affects Shared mode producers of partitioned topics only. It controls whether producers register and connect immediately to the owner broker of each partition or start lazily on demand. The internal producer of one partition is always started eagerly, chosen by the routing policy, but the internal producers of any additional partitions are started on demand, upon receiving their first message. Using this mode can reduce the strain on brokers for topics with large numbers of partitions and when the SinglePartition or some custom partial partition routing policy like PartialRoundRobinMessageRouterImpl is used without keyed messages. Because producer connection can be on demand, this can produce extra send latency for the first messages of a given partition.
      Parameters:
      lazyStartPartitionedProducers - whether to start partition producers lazily
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.enableLazyStartPartitionedProducers(boolean)

    • property

      default ReactiveMessageSenderBuilder<T> property(String key, String value)
      Adds a property to the producer. This setting applies to each producer created under this sender.

      Properties are application defined metadata that can be attached to the sender. When getting the topic stats, this metadata will be associated to the sender stats for easier identification.

      Parameters:
      key - the key of the property to add
      value - the value of the property to add
      Returns:
      the producer builder instance
      See Also:
      • ProducerBuilder.property(String, String)

    • properties

      default ReactiveMessageSenderBuilder<T> properties(Map<String,String> properties)
      Sets the properties to the producer. This setting applies to each producer created under this sender.

      Properties are application defined metadata that can be attached to the sender. When getting the topic stats, this metadata will be associated to the sender stats for easier identification.

      Parameters:
      properties - the properties to set
      Returns:
      the sender builder instance
      See Also:
      • ProducerBuilder.properties(Map)

    • build

      ReactiveMessageSender<T> build()
      Builds the reactive message sender.
      Returns:
      the reactive message sender