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 Detail

      • toImmutableSpec

        default ReactiveMessageConsumerSpec toImmutableSpec()
        Converts this builder to an immutable 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​(java.lang.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​(java.lang.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​(java.util.List<java.lang.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​(java.util.regex.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​(java.time.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​(java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(java.lang.String key,
                                                               java.lang.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​(java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(java.lang.String key,
                                                   java.lang.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​(java.lang.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​(java.time.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​(java.time.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​(java.time.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​(java.time.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:
        MessageResult.negativeAcknowledge(Message), ConsumerBuilder.negativeAckRedeliveryDelay(long, TimeUnit)

      • 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)

      • maxTotalReceiverQueueSizeAcrossPartitions

        default ReactiveMessageConsumerBuilder<T> maxTotalReceiverQueueSizeAcrossPartitions​(java.lang.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​(java.time.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​(java.lang.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​(java.time.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