Package org.apache.pulsar.client.api

Interface ReaderBuilder<T>

    • Method Detail

      • create

        Reader<T> create()
          throws PulsarClientException
        Finalize the creation of the Reader instance.

        This method will block until the reader is created successfully or an exception is thrown.

        Returns:
        the reader instance
        Throws:
        PulsarClientException - if the reader creation fails

      • createAsync

        java.util.concurrent.CompletableFuture<Reader<T>> createAsync()
        Finalize the creation of the Reader instance in asynchronous mode.

        This method will return a CompletableFuture that can be used to access the instance when it's ready.

        Returns:
        the reader instance
        Throws:
        PulsarClientException - if the reader creation fails

      • loadConf

        ReaderBuilder<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("topicName", "test-topic");
 config.put("receiverQueueSize", 2000);

 ReaderBuilder<byte[]> builder = ...;
 builder = builder.loadConf(config);

 Reader<byte[]> reader = builder.create();
        Parameters:
        config - configuration to load
        Returns:
        the reader builder instance

      • clone

        ReaderBuilder<T> clone()
        Create a copy of the current ReaderBuilder.

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

        
 ReaderBuilder<String> builder = client.newReader(Schema.STRING)
             .readerName("my-reader")
             .receiverQueueSize(10);

 Reader<String> reader1 = builder.clone().topic("topic-1").create();
 Reader<String> reader2 = builder.clone().topic("topic-2").create();
        Returns:
        a clone of the reader builder instance

      • topic

        ReaderBuilder<T> topic​(java.lang.String topicName)
        Specify the topic this reader will read from.

        This argument is required when constructing the reader.

        Parameters:
        topicName - the name of the topic
        Returns:
        the reader builder instance

      • topics

        ReaderBuilder<T> topics​(java.util.List<java.lang.String> topicNames)
        Specify topics this reader will read from.
        Parameters:
        topicNames -
        Returns:

      • startMessageId

        ReaderBuilder<T> startMessageId​(MessageId startMessageId)
        The initial reader positioning is done by specifying a message id. The options are:
        • MessageId.earliest: Start reading from the earliest message available in the topic
        • MessageId.latest: Start reading from end of the topic. The first message read will be the one published *after* the creation of the builder
        • MessageId: Position the reader on a particular message. The first message read will be the one immediately *after* the specified message

        If the first message *after* the specified message is not the desired behaviour, use startMessageIdInclusive().

        Parameters:
        startMessageId - the message id where the reader will be initially positioned on
        Returns:
        the reader builder instance

      • startMessageFromRollbackDuration

        ReaderBuilder<T> startMessageFromRollbackDuration​(long rollbackDuration,
                                                  java.util.concurrent.TimeUnit timeunit)
        The initial reader positioning can be set at specific timestamp by providing total rollback duration. so, broker can find a latest message that was published before given duration.
        eg: rollbackDuration in minute = 5 suggests broker to find message which was published 5 mins back and set the inital position on that messageId.
        Parameters:
        rollbackDuration - duration which position should be rolled back.
        Returns:

      • cryptoKeyReader

        ReaderBuilder<T> cryptoKeyReader​(CryptoKeyReader cryptoKeyReader)
        Sets a CryptoKeyReader to decrypt the message payloads.
        Parameters:
        cryptoKeyReader - CryptoKeyReader object
        Returns:
        the reader builder instance

      • defaultCryptoKeyReader

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

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

        Parameters:
        privateKey - the private key that is always used to decrypt message payloads.
        Returns:
        the reader builder instance
        Since:
        2.8.0

      • defaultCryptoKeyReader

        ReaderBuilder<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.

        Parameters:
        privateKeys - the map of private key names and their URIs used to decrypt message payloads.
        Returns:
        the reader builder instance
        Since:
        2.8.0

      • receiverQueueSize

        ReaderBuilder<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.

        Default value is 1000 messages and should be good for most use cases.

        Parameters:
        receiverQueueSize - the new receiver queue size value
        Returns:
        the reader builder instance

      • readerName

        ReaderBuilder<T> readerName​(java.lang.String readerName)
        Specify a reader name.

        The reader name is purely informational and can used to track a particular reader in the reported stats. By default a randomly generated name is used.

        Parameters:
        readerName - the name to use for the reader
        Returns:
        the reader builder instance

      • subscriptionRolePrefix

        ReaderBuilder<T> subscriptionRolePrefix​(java.lang.String subscriptionRolePrefix)
        Set the subscription role prefix. The default prefix is "reader".
        Parameters:
        subscriptionRolePrefix -
        Returns:
        the reader builder instance

      • subscriptionName

        ReaderBuilder<T> subscriptionName​(java.lang.String subscriptionName)
        Set the subscription name.

        If subscriptionRolePrefix is set at the same time, this configuration will prevail

        Parameters:
        subscriptionName -
        Returns:
        the reader builder instance

      • readCompacted

        ReaderBuilder<T> readCompacted​(boolean readCompacted)
        If enabled, the reader 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 reader 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 when reading from a persistent topic. Attempting to enable it on non-persistent topics will lead to the reader create call throwing a PulsarClientException.

        Parameters:
        readCompacted - whether to read from the compacted topic
        Returns:
        the reader builder instance

      • keyHashRange

        ReaderBuilder<T> keyHashRange​(Range... ranges)
        Set key hash range of the reader, broker will only dispatch messages which hash of the message key contains by the specified key hash range. Multiple key hash ranges can be specified on a reader.

        Total hash range size is 65536, so the max end of the range should be less than or equal to 65535.

        Parameters:
        ranges - key hash ranges for a reader
        Returns:
        the reader builder instance

      • poolMessages

        ReaderBuilder<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 (for example, memory corruption, deserialization error, etc.).