程序包 org.apache.pulsar.client.api

接口 ConsumerBuilder<T>

    • 方法详细资料

      • clone

        ConsumerBuilder<T> clone()
        Create a copy of the current consumer builder.

        Cloning the builder can be used to share an incomplete configuration and specialize it multiple times. For example: 

        
 ConsumerBuilder<String> builder = client.newConsumer(Schema.STRING)
         .subscriptionName("my-subscription-name")
         .subscriptionType(SubscriptionType.Shared)
         .receiverQueueSize(10);

 Consumer<String> consumer1 = builder.clone().topic("my-topic-1").subscribe();
 Consumer<String> consumer2 = builder.clone().topic("my-topic-2").subscribe();
        返回:
        a cloned consumer builder object

      • loadConf

        ConsumerBuilder<T> loadConf​(java.util.Map<java.lang.String,​java.lang.Object> config)
        Load the configuration from provided config map.

        Example: 

        
 Map<String, Object> config = new HashMap<>();
 config.put("ackTimeoutMillis", 1000);
 config.put("receiverQueueSize", 2000);

 Consumer<byte[]> builder = client.newConsumer()
              .loadConf(config)
              .subscribe();

 Consumer<byte[]> consumer = builder.subscribe();
        参数:
        config - configuration to load
        返回:
        the consumer builder instance

      • subscribe

        Consumer<T> subscribe()
               throws PulsarClientException
        Finalize the Consumer creation by subscribing to the topic.

        If the subscription does not exist, a new subscription will be created. By default the subscription will be created at the end of the topic. See subscriptionInitialPosition(SubscriptionInitialPosition) to configure the initial position behavior.

        Once a subscription is created, it will retain the data and the subscription cursor even if the consumer is not connected.

        返回:
        the consumer builder instance
        抛出:
        PulsarClientException - if the the subscribe operation fails

      • subscribeAsync

        java.util.concurrent.CompletableFuture<Consumer<T>> subscribeAsync()
        Finalize the Consumer creation by subscribing to the topic in asynchronous mode.

        If the subscription does not exist, a new subscription will be created. By default the subscription will be created at the end of the topic. See subscriptionInitialPosition(SubscriptionInitialPosition) to configure the initial position behavior.

        Once a subscription is created, it will retain the data and the subscription cursor even if the consumer is not connected.

        返回:
        a future that will yield a Consumer instance
        抛出:
        PulsarClientException - if the the subscribe operation fails

      • topic

        ConsumerBuilder<T> topic​(java.lang.String... topicNames)
        Specify the topics this consumer will subscribe on.
        参数:
        topicNames - a set of topic that the consumer will subscribe on
        返回:
        the consumer builder instance

      • topics

        ConsumerBuilder<T> topics​(java.util.List<java.lang.String> topicNames)
        Specify a list of topics that this consumer will subscribe on.
        参数:
        topicNames - a list of topic that the consumer will subscribe on
        返回:
        the consumer builder instance

      • topicsPattern

        ConsumerBuilder<T> topicsPattern​(java.util.regex.Pattern topicsPattern)
        Specify 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.

        参数:
        topicsPattern - a regular expression to select a list of topics to subscribe to
        返回:
        the consumer builder instance

      • topicsPattern

        ConsumerBuilder<T> topicsPattern​(java.lang.String topicsPattern)
        Specify a pattern for topics that this consumer will subscribe on.

        It accepts regular expression and will be compiled into a pattern internally. Eg. "persistent://public/default/pattern-topic-.*"

        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.

        参数:
        topicsPattern - given regular expression for topics pattern
        返回:
        the consumer builder instance

      • subscriptionName

        ConsumerBuilder<T> subscriptionName​(java.lang.String subscriptionName)
        Specify the subscription name for this consumer.

        This argument is required when constructing the consumer.

        参数:
        subscriptionName - the name of the subscription that this consumer should attach to
        返回:
        the consumer builder instance

      • ackTimeout

        ConsumerBuilder<T> ackTimeout​(long ackTimeout,
                              java.util.concurrent.TimeUnit timeUnit)
        Set the timeout for unacked messages, truncated to the nearest millisecond. The timeout needs to be greater than 1 second.

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

        When enabling ack 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).

        参数:
        ackTimeout - for unacked messages.
        timeUnit - unit in which the timeout is provided.
        返回:
        the consumer builder instance

      • isAckReceiptEnabled

        ConsumerBuilder<T> isAckReceiptEnabled​(boolean isAckReceiptEnabled)
        Ack will return receipt but does not mean that the message will not be resent after get receipt.
        参数:
        isAckReceiptEnabled - Boolean is enable ack for receipt
        返回:
        the consumer builder instance

      • ackTimeoutTickTime

        ConsumerBuilder<T> ackTimeoutTickTime​(long tickTime,
                                      java.util.concurrent.TimeUnit timeUnit)
        Define the granularity of the ack-timeout redelivery.

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

        参数:
        tickTime - the min precision for the ack timeout messages tracker
        timeUnit - unit in which the timeout is provided.
        返回:
        the consumer builder instance

      • negativeAckRedeliveryDelay

        ConsumerBuilder<T> negativeAckRedeliveryDelay​(long redeliveryDelay,
                                              java.util.concurrent.TimeUnit timeUnit)
        Set the delay to wait before re-delivering messages that have failed to be process.

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

        参数:
        redeliveryDelay - redelivery delay for failed messages
        timeUnit - unit in which the timeout is provided.
        返回:
        the consumer builder instance
        另请参阅:
        Consumer.negativeAcknowledge(Message)

      • cryptoKeyReader

        ConsumerBuilder<T> cryptoKeyReader​(CryptoKeyReader cryptoKeyReader)
        Sets a CryptoKeyReader.

        Configure the key reader to be used to decrypt the message payloads.

        参数:
        cryptoKeyReader - CryptoKeyReader object
        返回:
        the consumer builder instance

      • defaultCryptoKeyReader

        ConsumerBuilder<T> defaultCryptoKeyReader​(java.lang.String privateKey)
        Sets the default implementation of CryptoKeyReader.

        Configure the key reader to be used to decrypt the message payloads.

        参数:
        privateKey - the private key that is always used to decrypt message payloads.
        返回:
        the consumer builder instance
        从以下版本开始:
        2.8.0

      • defaultCryptoKeyReader

        ConsumerBuilder<T> defaultCryptoKeyReader​(java.util.Map<java.lang.String,​java.lang.String> privateKeys)
        Sets the default implementation of CryptoKeyReader.

        Configure the key reader to be used to decrypt the message payloads.

        参数:
        privateKeys - the map of private key names and their URIs used to decrypt message payloads.
        返回:
        the consumer builder instance
        从以下版本开始:
        2.8.0

      • messageCrypto

        ConsumerBuilder<T> messageCrypto​(MessageCrypto messageCrypto)
        Sets a MessageCrypto.

        Contains methods to encrypt/decrypt message for End to End Encryption.

        参数:
        messageCrypto - MessageCrypto object
        返回:
        the consumer builder instance

      • cryptoFailureAction

        ConsumerBuilder<T> cryptoFailureAction​(ConsumerCryptoFailureAction action)
        Sets the ConsumerCryptoFailureAction to the value specified.
        参数:
        action - the action the consumer will take in case of decryption failures
        返回:
        the consumer builder instance

      • receiverQueueSize

        ConsumerBuilder<T> receiverQueueSize​(int receiverQueueSize)
        Sets the size of the consumer receive queue.

        The consumer receive queue controls how many messages can be accumulated by the Consumer before the application calls Consumer.receive(). Using a higher value could potentially increase the consumer throughput at the expense of bigger memory utilization.

        Setting the consumer queue size as zero

        • Decreases the throughput of the consumer, by disabling pre-fetching of messages. This approach improves the message distribution on shared subscription, by pushing messages only to the consumers that are ready to process them. Neither Consumer.receive(int, TimeUnit) nor Partitioned Topics can be used if the consumer queue size is zero. Consumer.receive() function call should not be interrupted when the consumer queue size is zero.
        • Doesn't support Batch-Message: if consumer receives any batch-message then it closes consumer connection with broker and Consumer.receive() call will remain blocked while Consumer.receiveAsync() receives exception in callback. consumer will not be able receive any further message unless batch-message in pipeline is removed
        Default value is 1000 messages and should be good for most use cases.
        参数:
        receiverQueueSize - the new receiver queue size value
        返回:
        the consumer builder instance

      • acknowledgmentGroupTime

        ConsumerBuilder<T> acknowledgmentGroupTime​(long delay,
                                           java.util.concurrent.TimeUnit unit)
        Group the consumer acknowledgments for the specified time.

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

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

        参数:
        delay - the max amount of time an acknowledgemnt can be delayed
        unit - the time unit for the delay
        返回:
        the consumer builder instance

      • replicateSubscriptionState

        ConsumerBuilder<T> replicateSubscriptionState​(boolean replicateSubscriptionState)
        参数:
        replicateSubscriptionState -

      • maxTotalReceiverQueueSizeAcrossPartitions

        ConsumerBuilder<T> maxTotalReceiverQueueSizeAcrossPartitions​(int maxTotalReceiverQueueSizeAcrossPartitions)
        Set the max total receiver queue size across partitons.

        This setting will be used to reduce the receiver queue size for individual partitions receiverQueueSize(int) 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.

        参数:
        maxTotalReceiverQueueSizeAcrossPartitions - max pending messages across all the partitions
        返回:
        the consumer builder instance

      • consumerName

        ConsumerBuilder<T> consumerName​(java.lang.String consumerName)
        Set the consumer name.

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

        参数:
        consumerName -
        返回:
        the consumer builder instance

      • consumerEventListener

        ConsumerBuilder<T> consumerEventListener​(ConsumerEventListener consumerEventListener)
        Sets a ConsumerEventListener for the consumer.

        The consumer group listener is used for receiving consumer state change in a consumer group for failover subscription. Application can then react to the consumer state changes.

        参数:
        consumerEventListener - the consumer group listener object
        返回:
        the consumer builder instance

      • readCompacted

        ConsumerBuilder<T> readCompacted​(boolean readCompacted)
        If enabled, 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 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 topics or on a shared subscription, will lead to the subscription call throwing a PulsarClientException.

        参数:
        readCompacted - whether to read from the compacted topic
        返回:
        the consumer builder instance

      • patternAutoDiscoveryPeriod

        ConsumerBuilder<T> patternAutoDiscoveryPeriod​(int periodInMinutes)
        Set topics auto discovery period when using a pattern for topics consumer. The period is in minute, and default and minimum value is 1 minute.
        参数:
        periodInMinutes - number of minutes between checks for new topics matching pattern set with topicsPattern(String)
        返回:
        the consumer builder instance

      • patternAutoDiscoveryPeriod

        ConsumerBuilder<T> patternAutoDiscoveryPeriod​(int interval,
                                              java.util.concurrent.TimeUnit unit)
        Set topics auto discovery period when using a pattern for topics consumer.
        参数:
        interval - the amount of delay between checks for new topics matching pattern set with topicsPattern(String)
        unit - the unit of the topics auto discovery period
        返回:
        the consumer builder instance

      • priorityLevel

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

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

        If subscription has consumer-A with priorityLevel 0 and Consumer-B with priorityLevel 1 then broker will dispatch messages to only consumer-A until it runs out permit and then broker starts 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 broker dispatches messages to consumers: C1, C2, C3, C1, C4, C5, C4

        Failover subscription Broker selects active consumer for a failover-subscription based on consumer's priority-level and lexicographical sorting of a consumer name. 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:
 Broker evenly assigns partitioned topics to highest priority consumers.
        参数:
        priorityLevel - the priority of this consumer
        返回:
        the consumer builder instance

      • property

        ConsumerBuilder<T> property​(java.lang.String key,
                            java.lang.String value)
        Set a name/value property with this 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.

        参数:
        key - the property key
        value - the property value
        返回:
        the consumer builder instance

      • properties

        ConsumerBuilder<T> properties​(java.util.Map<java.lang.String,​java.lang.String> properties)
        Add all the properties in the provided map 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.

        参数:
        properties - the map with properties
        返回:
        the consumer builder instance

      • subscriptionTopicsMode

        ConsumerBuilder<T> subscriptionTopicsMode​(RegexSubscriptionMode regexSubscriptionMode)
        Determines to which topics this consumer should be subscribed to - Persistent, Non-Persistent, or both. Only used with pattern subscriptions.
        参数:
        regexSubscriptionMode - Pattern subscription mode

      • deadLetterPolicy

        ConsumerBuilder<T> deadLetterPolicy​(DeadLetterPolicy deadLetterPolicy)
        Set dead letter policy for consumer.

        By default some message will redelivery so many times possible, even to the extent that it can be never stop. By using dead letter mechanism messages will has the max redelivery count, when message exceeding the maximum number of redeliveries, message will send to the Dead Letter Topic and acknowledged automatic.

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

         client.newConsumer()
          .deadLetterPolicy(DeadLetterPolicy.builder().maxRedeliverCount(10).build())
          .subscribe();
        Default dead letter topic name is {TopicName}-{Subscription}-DLQ. To setting a custom dead letter topic name 
         client.newConsumer()
          .deadLetterPolicy(DeadLetterPolicy
              .builder()
              .maxRedeliverCount(10)
              .deadLetterTopic("your-topic-name")
              .build())
          .subscribe();
        When a dead letter policy is specified, and no ackTimeoutMillis is specified, then the ack timeout will be set to 30000 millisecond.

      • autoUpdatePartitions

        ConsumerBuilder<T> autoUpdatePartitions​(boolean autoUpdate)
        If enabled, the consumer will auto subscribe for partitions increasement. This is only for partitioned consumer.
        参数:
        autoUpdate - whether to auto update partition increasement

      • autoUpdatePartitionsInterval

        ConsumerBuilder<T> autoUpdatePartitionsInterval​(int interval,
                                                java.util.concurrent.TimeUnit unit)
        Set the interval of updating partitions (default: 1 minute). This only works if autoUpdatePartitions is enabled.
        参数:
        interval - the interval of updating partitions
        unit - the time unit of the interval.
        返回:
        the consumer builder instance

      • keySharedPolicy

        ConsumerBuilder<T> keySharedPolicy​(KeySharedPolicy keySharedPolicy)
        Set KeyShared subscription policy for consumer.

        By default, KeyShared subscription use auto split hash range to maintain consumers. If you want to set a different KeyShared policy, you can set by following example: 

         client.newConsumer()
          .keySharedPolicy(KeySharedPolicy.stickyHashRange().ranges(Range.of(0, 10)))
          .subscribe();
        Details about sticky hash range policy, please see KeySharedPolicy.KeySharedPolicySticky.

        Or 

         client.newConsumer()
          .keySharedPolicy(KeySharedPolicy.autoSplitHashRange())
          .subscribe();
        Details about auto split hash range policy, please see KeySharedPolicy.KeySharedPolicyAutoSplit.
        参数:
        keySharedPolicy - The KeySharedPolicy want to specify

      • batchReceivePolicy

        ConsumerBuilder<T> batchReceivePolicy​(BatchReceivePolicy batchReceivePolicy)
        Set batch receive policy BatchReceivePolicy for consumer. By default, consumer will use BatchReceivePolicy.DEFAULT_POLICY as batch receive policy.

        Example: 

         client.newConsumer().batchReceivePolicy(BatchReceivePolicy.builder()
              .maxNumMessages(100)
              .maxNumBytes(5 * 1024 * 1024)
              .timeout(100, TimeUnit.MILLISECONDS)
              .build()).subscribe();

      • enableRetry

        ConsumerBuilder<T> enableRetry​(boolean retryEnable)
        If enabled, the consumer will auto retry message. default unabled.
        参数:
        retryEnable - whether to auto retry message

      • enableBatchIndexAcknowledgment

        ConsumerBuilder<T> enableBatchIndexAcknowledgment​(boolean batchIndexAcknowledgmentEnabled)
        Enable or disable the batch index acknowledgment. To enable this feature must ensure batch index acknowledgment feature is enabled at the broker side.

      • maxPendingChuckedMessage

        @Deprecated
ConsumerBuilder<T> maxPendingChuckedMessage​(int maxPendingChuckedMessage)
        已过时。
        use maxPendingChunkedMessage(int)
        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 and it can be guarded by providing this @maxPendingChuckedMessage threshold. Once, consumer reaches this threshold, it drops the outstanding unchunked-messages by silently acking or asking broker to redeliver later by marking it unacked. This behavior can be controlled by configuration: @autoAckOldestChunkedMessageOnQueueFull
        参数:
        maxPendingChuckedMessage -
        返回:

      • maxPendingChunkedMessage

        ConsumerBuilder<T> maxPendingChunkedMessage​(int maxPendingChunkedMessage)
        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 and it can be guarded by providing this @maxPendingChunkedMessage threshold. Once, consumer reaches this threshold, it drops the outstanding unchunked-messages by silently acking or asking broker to redeliver later by marking it unacked. This behavior can be controlled by configuration: @autoAckOldestChunkedMessageOnQueueFull
        参数:
        maxPendingChunkedMessage -
        返回:

      • autoAckOldestChunkedMessageOnQueueFull

        ConsumerBuilder<T> autoAckOldestChunkedMessageOnQueueFull​(boolean autoAckOldestChunkedMessageOnQueueFull)
        Buffering large number of outstanding uncompleted chunked messages can create memory pressure and it can be guarded by providing this @maxPendingChunkedMessage threshold. Once, consumer reaches this threshold, it drops the outstanding unchunked-messages by silently acking if autoAckOldestChunkedMessageOnQueueFull is true else it marks them for redelivery.
        参数:
        autoAckOldestChunkedMessageOnQueueFull -
        返回:

      • expireTimeOfIncompleteChunkedMessage

        ConsumerBuilder<T> expireTimeOfIncompleteChunkedMessage​(long duration,
                                                        java.util.concurrent.TimeUnit unit)
        If producer fails to publish all the chunks of a message then consumer can expire incomplete chunks if consumer won't be able to receive all chunks in expire times (default 1 hour).
        参数:
        duration -
        unit -
        返回:

      • poolMessages

        ConsumerBuilder<T> poolMessages​(boolean poolMessages)
        Enable pooling of messages and the underlying data buffers.

        When pooling is enabled, the application is responsible for calling Message.release() after the handling of every received message. If “release()” is not called on a received message, there will be a memory leak. If an application attempts to use and already “released” message, it might experience undefined behavior (eg: memory corruption, deserialization error, etc.).