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

Interface ReactiveMessageConsumerBuilder<T>

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

  • Method Details

    • applySpec

      default ReactiveMessageConsumerBuilder<T> applySpec(ReactiveMessageConsumerSpec consumerSpec)
      Apply a consumer spec to configure the consumer.
      Parameters:
      consumerSpec - the consumer spec to apply
      Returns:
      the consumer builder instance

    • toImmutableSpec

      default ReactiveMessageConsumerSpec toImmutableSpec()
      Converts this builder to an immutable reactive consumer spec.
      Returns:
      the reactive consumer spec.

    • getMutableSpec

      MutableReactiveMessageConsumerSpec getMutableSpec()
      Converts this builder to a mutable reactive consumer spec.
      Returns:
      the reactive consumer spec.

    • clone

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

    • topic

      default ReactiveMessageConsumerBuilder<T> topic(String topicName)
      Adds a topic this consumer will subscribe on.
      Parameters:
      topicName - a topic that the consumer will subscribe on
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.topic(String...)

    • topic

      default ReactiveMessageConsumerBuilder<T> topic(String... topicNames)
      Adds topics this consumer will subscribe on.
      Parameters:
      topicNames - a set of topic that the consumer will subscribe on
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.topic(String...)

    • topics

      default ReactiveMessageConsumerBuilder<T> topics(List<String> topicNames)
      Sets the topics this consumer will subscribe on.
      Parameters:
      topicNames - a set of topic that the consumer will subscribe on
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.topics(List)

    • topicsPattern

      default ReactiveMessageConsumerBuilder<T> topicsPattern(Pattern topicsPattern)
      Sets a pattern for topics that this consumer will subscribe on.

      The pattern will be applied to subscribe to all the topics, within a single namespace, that will match the pattern.

      The consumer will automatically subscribe to topics created after itself.

      Parameters:
      topicsPattern - a regular expression to select a list of topics to subscribe to
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.topicsPattern(Pattern)

    • topicsPatternSubscriptionMode

      default ReactiveMessageConsumerBuilder<T> topicsPatternSubscriptionMode(org.apache.pulsar.client.api.RegexSubscriptionMode topicsPatternSubscriptionMode)
      Sets to which topics this consumer should be subscribed to - Persistent, Mon-Persistent, or both. Only used with pattern subscriptions.
      Parameters:
      topicsPatternSubscriptionMode - pattern subscription mode
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionTopicsMode(RegexSubscriptionMode)

    • topicsPatternAutoDiscoveryPeriod

      default ReactiveMessageConsumerBuilder<T> topicsPatternAutoDiscoveryPeriod(Duration topicsPatternAutoDiscoveryPeriod)
      Sets the topics auto discovery period when using a pattern for topics consumer.
      Parameters:
      topicsPatternAutoDiscoveryPeriod - duration between checks for new topics matching pattern set with topicsPattern(Pattern)
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.patternAutoDiscoveryPeriod(int, TimeUnit)

    • subscriptionName

      default ReactiveMessageConsumerBuilder<T> subscriptionName(String subscriptionName)
      Sets the subscription name for this consumer.

      This argument is required when constructing the consumer.

      Parameters:
      subscriptionName - the name of the subscription that this consumer should attach to
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionName(String)

    • subscriptionMode

      default ReactiveMessageConsumerBuilder<T> subscriptionMode(org.apache.pulsar.client.api.SubscriptionMode subscriptionMode)
      Sets the subscription mode to be used when subscribing to the topic.

      Options are:

      • SubscriptionMode.Durable (Default)
      • SubscriptionMode.NonDurable
      Parameters:
      subscriptionMode - the subscription mode value
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionMode(SubscriptionMode)

    • subscriptionType

      default ReactiveMessageConsumerBuilder<T> subscriptionType(org.apache.pulsar.client.api.SubscriptionType subscriptionType)
      Sets the subscription type to be used when subscribing to the topic.

      Options are:

      • SubscriptionType.Exclusive (Default)
      • SubscriptionType.Failover
      • SubscriptionType.Shared
      Parameters:
      subscriptionType - the subscription type value
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionType(SubscriptionType)

    • subscriptionInitialPosition

      default ReactiveMessageConsumerBuilder<T> subscriptionInitialPosition(org.apache.pulsar.client.api.SubscriptionInitialPosition subscriptionInitialPosition)
      Sets the initial position of the subscription for the consumer.
      Parameters:
      subscriptionInitialPosition - the position where to initialize a newly created subscription
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionInitialPosition(SubscriptionInitialPosition)

    • keySharedPolicy

      default ReactiveMessageConsumerBuilder<T> keySharedPolicy(org.apache.pulsar.client.api.KeySharedPolicy keySharedPolicy)
      Sets the KeyShared subscription policy for the consumer.

      By default, KeyShared subscription uses auto split hash range to maintain consumers. If you want to set a different KeyShared policy, you can set it like this: 

       client.messageConsumer(Schema.BYTES)
          .keySharedPolicy(KeySharedPolicy.stickyHashRange().ranges(Range.of(0, 10)))
          .build();
      For details about sticky hash range policy, please see KeySharedPolicy.KeySharedPolicySticky.

      Or 

       client.messageConsumer(Schema.BYTES)
          .keySharedPolicy(KeySharedPolicy.autoSplitHashRange())
          .build();
      For details about auto split hash range policy, please see KeySharedPolicy.KeySharedPolicyAutoSplit.
      Parameters:
      keySharedPolicy - the KeyShared policy to set
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.keySharedPolicy(KeySharedPolicy)

    • replicateSubscriptionState

      default ReactiveMessageConsumerBuilder<T> replicateSubscriptionState(boolean replicateSubscriptionState)
      Sets whether the subscription shall be replicated.
      Parameters:
      replicateSubscriptionState - whether the subscription shall be replicated
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.replicateSubscriptionState(boolean)

    • subscriptionProperties

      default ReactiveMessageConsumerBuilder<T> subscriptionProperties(Map<String,String> subscriptionProperties)
      Sets the subscription properties for this subscription. Properties are immutable, and consumers under the same subscription will fail to create a subscription if they use different properties.
      Parameters:
      subscriptionProperties - the subscription properties to set
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionProperties(Map)

    • subscriptionProperty

      default ReactiveMessageConsumerBuilder<T> subscriptionProperty(String key, String value)
      Adds a subscription property for this subscription. Properties are immutable, and consumers under the same subscription will fail to create a subscription if they use different properties.
      Parameters:
      key - the key of the property to add
      value - the value of the property to add
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.subscriptionProperties(Map)

    • consumerName

      default ReactiveMessageConsumerBuilder<T> consumerName(String consumerName)
      Sets the consumer name.

      Consumer name is informative and it can be used to identify a particular consumer instance from the topic stats.

      Parameters:
      consumerName - the consumer name
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.consumerName(String)

    • properties

      default ReactiveMessageConsumerBuilder<T> properties(Map<String,String> properties)
      Sets the properties for the consumer.

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

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

    • property

      default ReactiveMessageConsumerBuilder<T> property(String key, String value)
      Adds a property to the consumer.

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

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

    • priorityLevel

      default ReactiveMessageConsumerBuilder<T> priorityLevel(Integer priorityLevel)
      Sets the priority level for the consumer.

      Shared subscription Sets the priority level for the shared subscription consumers to which the broker gives more priority while dispatching messages. Here, the broker follows descending priorities. (eg: 0=max-priority, 1, 2,..)

      In Shared subscription mode, the broker will first dispatch messages to max priority-level consumers if they have permits, else the broker will consider next priority level consumers.

      If the subscription has consumer-A with priorityLevel 0 and consumer-B with priorityLevel 1 then the broker will dispatch messages only to consumer-A until it runs out of permits, then the broker will start dispatching messages to consumer-B. 

       Consumer PriorityLevel Permits
 C1       0             2
 C2       0             1
 C3       0             1
 C4       1             2
 C5       1             1
 Order in which the broker dispatches messages to consumers: C1, C2, C3, C1, C4, C5, C4

      Failover subscription The broker selects the active consumer for a failover-subscription based on the consumer priority-level and lexicographical sorting of consumer names. eg: 

       1. Active consumer = C1 : Same priority-level and lexicographical sorting
 Consumer PriorityLevel Name
 C1       0             aaa
 C2       0             bbb

 2. Active consumer = C2 : Consumer with highest priority
 Consumer PriorityLevel Name
 C1       1             aaa
 C2       0             bbb

 Partitioned-topics:
 The broker evenly assigns partitioned topics to highest priority consumers.
      Parameters:
      priorityLevel - the priority level of this consumer
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.priorityLevel(int)

    • readCompacted

      default ReactiveMessageConsumerBuilder<T> readCompacted(boolean readCompacted)
      Sets whether the consumer will read messages from the compacted topic rather than reading the full message backlog of the topic. This means that, if the topic has been compacted, the consumer will only see the latest value for each key in the topic, up until the point in the topic message backlog that has been compacted. Beyond that point, the messages will be sent as normal.

      readCompacted can only be enabled for subscriptions to persistent topics, which have a single active consumer (i.e. failure or exclusive subscriptions). Attempting to enable it on subscriptions to a non-persistent topic or on a shared subscription, will lead to the subscription call throwing a PulsarClientException.

      Parameters:
      readCompacted - whether to read from the compacted topic
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.readCompacted(boolean)

    • batchIndexAckEnabled

      default ReactiveMessageConsumerBuilder<T> batchIndexAckEnabled(boolean batchIndexAckEnabled)
      Enables or disables the batch index acknowledgment. For the batch index acknowledgment feature to work, it must also be enabled on the broker.
      Parameters:
      batchIndexAckEnabled - whether to enable batch index acknowledgment
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.enableBatchIndexAcknowledgment(boolean)

    • ackTimeout

      default ReactiveMessageConsumerBuilder<T> ackTimeout(Duration ackTimeout)
      Sets the timeout for unacknowledged messages, truncated to the nearest millisecond. The timeout needs to be greater than 1 second.

      By default, the acknowledgement timeout is disabled and that means that messages delivered to a consumer will not be re-delivered unless the consumer crashes.

      When enabling the acknowledgement timeout, if a message is not acknowledged within the specified timeout it will be re-delivered to the consumer (possibly to a different consumer in case of a shared subscription).

      Parameters:
      ackTimeout - the timeout for unacknowledged messages.
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.ackTimeout(long, TimeUnit)

    • ackTimeoutTickTime

      default ReactiveMessageConsumerBuilder<T> ackTimeoutTickTime(Duration ackTimeoutTickTime)
      Sets the granularity of the ack-timeout redelivery.

      By default, the tick time is set to 1 second. Using a higher tick time will reduce the memory overhead to track messages when the ack-timeout is set to bigger values (eg: 1hour).

      Parameters:
      ackTimeoutTickTime - the minimum precision for the acknowledgement timeout messages tracker
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.ackTimeoutTickTime(long, TimeUnit)

    • acknowledgementsGroupTime

      default ReactiveMessageConsumerBuilder<T> acknowledgementsGroupTime(Duration acknowledgementsGroupTime)
      Sets the duration for grouping the acknowledgement messages.

      By default, the consumer will use a 100 ms grouping time to send the acknowledgements to the broker.

      Setting a group time of 0, will send the acknowledgements immediately. A longer acknowledgement group time will be more efficient at the expense of a slight increase in message re-deliveries after a failure.

      Parameters:
      acknowledgementsGroupTime - the duration for grouping the acknowledgement messages
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.acknowledgmentGroupTime(long, TimeUnit)

    • acknowledgeAsynchronously

      default ReactiveMessageConsumerBuilder<T> acknowledgeAsynchronously(boolean acknowledgeAsynchronously)
      When set to true, ignores the acknowledge operation completion and makes it asynchronous from the message consuming processing to improve performance by allowing the acknowledges and message processing to interleave. Defaults to true.
      Parameters:
      acknowledgeAsynchronously - when set to true, ignores the acknowledge operation completion
      Returns:
      the consumer builder instance

    • acknowledgeScheduler

      default ReactiveMessageConsumerBuilder<T> acknowledgeScheduler(reactor.core.scheduler.Scheduler acknowledgeScheduler)
      Sets the scheduler to use to handle acknowledgements.
      Parameters:
      acknowledgeScheduler - the scheduler to use to handle acknowledgements
      Returns:
      the consumer builder instance

    • negativeAckRedeliveryDelay

      default ReactiveMessageConsumerBuilder<T> negativeAckRedeliveryDelay(Duration negativeAckRedeliveryDelay)
      Sets the delay to wait before re-delivering messages that have failed to be processed.

      When the application uses MessageResult.negativeAcknowledge(Message), the failed message will be redelivered after a fixed timeout. The default is 1 min.

      Parameters:
      negativeAckRedeliveryDelay - the redelivery delay for failed messages
      Returns:
      the consumer builder instance
      See Also:

    • deadLetterPolicy

      default ReactiveMessageConsumerBuilder<T> deadLetterPolicy(org.apache.pulsar.client.api.DeadLetterPolicy deadLetterPolicy)
      Sets a dead letter policy for the consumer.

      By default, messages are redelivered indefinitely if they are not acknowledged. By using a dead letter mechanism, messages that have reached the max redelivery count will be acknowledged automatically and send to the configured dead letter topic.

      You can enable the dead letter mechanism by setting a dead letter policy. Example: 

       client.messageConsumer(Schema.BYTES)
          .deadLetterPolicy(DeadLetterPolicy.builder().maxRedeliverCount(10).build())
          .build();
      Default the dead letter topic name is {TopicName}-{Subscription}-DLQ. You can set a custom dead letter topic name like this: 
       client.messageConsumer(Schema.BYTES)
          .deadLetterPolicy(DeadLetterPolicy
              .builder()
              .maxRedeliverCount(10)
              .deadLetterTopic("your-topic-name")
              .build())
          .build();
      When a dead letter policy is specified, and no acknowledgement timeout is specified, then the acknowledgement timeout will be set to 30000 millisecond.
      Parameters:
      deadLetterPolicy - the dead letter policy to use
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.deadLetterPolicy(DeadLetterPolicy)

    • retryLetterTopicEnable

      default ReactiveMessageConsumerBuilder<T> retryLetterTopicEnable(boolean retryLetterTopicEnable)
      Sets whether automatic routing to retry letter topic and dead letter topic are enabled.
      Parameters:
      retryLetterTopicEnable - whether to automatic retry/dead-letter topics are enabled
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.enableRetry(boolean)

    • receiverQueueSize

      default ReactiveMessageConsumerBuilder<T> receiverQueueSize(Integer receiverQueueSize)
      Sets the size of the consumer receiver queue.

      The consumer receiver queue controls how many messages can be accumulated by the ReactiveMessageConsumer before backpressure triggers. Using a higher value could potentially increase the consumer throughput at the expense of bigger memory utilization.

      Setting the consumer queue size to zero

      The default value is 1000 messages and should be good for most use cases.
      Parameters:
      receiverQueueSize - the receiver queue size value
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.receiverQueueSize(int)

    • maxTotalReceiverQueueSizeAcrossPartitions

      default ReactiveMessageConsumerBuilder<T> maxTotalReceiverQueueSizeAcrossPartitions(Integer maxTotalReceiverQueueSizeAcrossPartitions)
      Sets the maximum total receiver queue size across partitions.

      This setting is used to reduce the receiver queue size for individual partitions receiverQueueSize(Integer) if the total exceeds this value (default: 50000). The purpose of this setting is to have an upper-limit on the number of messages that a consumer can be pushed at once from a broker, across all the partitions.

      Parameters:
      maxTotalReceiverQueueSizeAcrossPartitions - the maximum pending messages across all the partitions
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.maxTotalReceiverQueueSizeAcrossPartitions(int)

    • autoUpdatePartitions

      default ReactiveMessageConsumerBuilder<T> autoUpdatePartitions(boolean autoUpdatePartitions)
      Sets whether the consumer shall automatically subscribe to new partitions added to the topic. This is only for partitioned topics.
      Parameters:
      autoUpdatePartitions - whether to automatically subscribe to new partitions
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.autoUpdatePartitions(boolean)

    • autoUpdatePartitionsInterval

      default ReactiveMessageConsumerBuilder<T> autoUpdatePartitionsInterval(Duration autoUpdatePartitionsInterval)
      Sets the interval for checking partitions updates (default: 1 minute). This only applies if autoUpdatePartitions(boolean) is enabled.
      Parameters:
      autoUpdatePartitionsInterval - the interval for checking partitions updates
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.autoUpdatePartitionsInterval(int, TimeUnit)

    • cryptoKeyReader

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

    • cryptoFailureAction

      default ReactiveMessageConsumerBuilder<T> cryptoFailureAction(org.apache.pulsar.client.api.ConsumerCryptoFailureAction cryptoFailureAction)
      Sets the action the consumer will take in case of decryption failures.
      Parameters:
      cryptoFailureAction - the action the consumer will take in case of decryption failures
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.cryptoFailureAction(ConsumerCryptoFailureAction)

    • maxPendingChunkedMessage

      default ReactiveMessageConsumerBuilder<T> maxPendingChunkedMessage(Integer maxPendingChunkedMessage)
      Sets the maximum pending chunked messages. Consumer buffers chunk messages into memory until it receives all the chunks of the original message. While consuming chunk-messages, chunks from same message might not be contiguous in the stream and they might be mixed with other messages' chunks. so, consumer has to maintain multiple buffers to manage chunks coming from different messages. This mainly happens when multiple publishers are publishing messages on the topic concurrently or publisher failed to publish all chunks of the messages. 
       eg: M1-C1, M2-C1, M1-C2, M2-C2
 Here, Messages M1-C1 and M1-C2 belong to original message M1, M2-C1 and M2-C2 messages belong to M2 message.
      Buffering large number of outstanding uncompleted chunked messages can create memory pressure. It can be guarded by providing a maxPendingChunkedMessage threshold. Once the consumer reaches this threshold, it drops the outstanding non-chunked messages by silently acknowledging or asking the broker to redeliver later by marking it unacknowledged. This behavior can be controlled by setting autoAckOldestChunkedMessageOnQueueFull(boolean) The default value is 10.
      Parameters:
      maxPendingChunkedMessage - the maximum pending chunked messages.
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.maxPendingChunkedMessage(int)

    • autoAckOldestChunkedMessageOnQueueFull

      default ReactiveMessageConsumerBuilder<T> autoAckOldestChunkedMessageOnQueueFull(boolean autoAckOldestChunkedMessageOnQueueFull)
      Sets whether non-chunked messages are silently acknowledged when maxPendingChunkedMessage is reached. Buffering large number of outstanding uncompleted chunked messages can create memory pressure. It can be guarded by providing maxPendingChunkedMessage(java.lang.Integer) threshold. Once the consumer reaches this threshold, it drops the outstanding non-chunked messages by silently acknowledging if autoAckOldestChunkedMessageOnQueueFull is true or else it marks them for redelivery. Defaults to false.
      Parameters:
      autoAckOldestChunkedMessageOnQueueFull - whether non-chunked messages are silently acknowledged
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.autoAckOldestChunkedMessageOnQueueFull(boolean)

    • expireTimeOfIncompleteChunkedMessage

      default ReactiveMessageConsumerBuilder<T> expireTimeOfIncompleteChunkedMessage(Duration expireTimeOfIncompleteChunkedMessage)
      Sets the duration after which incomplete chunked messages are expired (happens for instance if the producer fails to publish all the chunks).
      Parameters:
      expireTimeOfIncompleteChunkedMessage - the duration after which incomplete chunked messages are expired
      Returns:
      the consumer builder instance
      See Also:
      • ConsumerBuilder.expireTimeOfIncompleteChunkedMessage(long, TimeUnit)

    • build

      ReactiveMessageConsumer<T> build()
      Builds the reactive message consumer.
      Returns:
      the reactive message consumer