org.apache.pulsar.client.api.ReaderBuilder Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.pulsar.client.api;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import org.apache.pulsar.common.classification.InterfaceAudience;
import org.apache.pulsar.common.classification.InterfaceStability;
/**
* {@link ReaderBuilder} is used to configure and create instances of {@link Reader}.
*
* @see PulsarClient#newReader()
*
* @since 2.0.0
*/
@InterfaceAudience.Public
@InterfaceStability.Stable
public interface ReaderBuilder extends Cloneable {
/**
* Finalize the creation of the {@link Reader} instance.
*
* This method will block until the reader is created successfully or an exception is thrown.
*
* @return the reader instance
* @throws PulsarClientException
* if the reader creation fails
*/
Reader create() throws PulsarClientException;
/**
* Finalize the creation of the {@link Reader} instance in asynchronous mode.
*
* This method will return a {@link CompletableFuture} that can be used to access the instance when it's ready.
*
* @return the reader instance
* @throws PulsarClientException
* if the reader creation fails
*/
CompletableFuture> createAsync();
/**
* Load the configuration from provided config map.
*
* Example:
*
*
{@code
* Map config = new HashMap<>();
* config.put("topicName", "test-topic");
* config.put("receiverQueueSize", 2000);
*
* ReaderBuilder builder = ...;
* builder = builder.loadConf(config);
*
* Reader reader = builder.create();
* }
*
* @param config
* configuration to load
* @return the reader builder instance
*/
ReaderBuilder loadConf(Map config);
/**
* Create a copy of the current {@link ReaderBuilder}.
*
* Cloning the builder can be used to share an incomplete configuration and specialize it multiple times. For
* example:
*
*
{@code
* ReaderBuilder builder = client.newReader(Schema.STRING)
* .readerName("my-reader")
* .receiverQueueSize(10);
*
* Reader reader1 = builder.clone().topic("topic-1").create();
* Reader reader2 = builder.clone().topic("topic-2").create();
* }
*
* @return a clone of the reader builder instance
*/
ReaderBuilder clone();
/**
* Specify the topic this reader will read from.
*
* This argument is required when constructing the reader.
*
* @param topicName
* the name of the topic
* @return the reader builder instance
*/
ReaderBuilder topic(String topicName);
/**
* Specify topics this reader will read from.
* @param topicNames
* @return
*/
ReaderBuilder topics(List topicNames);
/**
* The initial reader positioning is done by specifying a message id. The options are:
*
* - {@link MessageId#earliest}: Start reading from the earliest message available in the topic
* - {@link MessageId#latest}: Start reading from end of the topic. The first message read will be the one
* published *after* the creation of the builder
* - {@link 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
* {@link ReaderBuilder#startMessageIdInclusive()}.
*
* @param startMessageId the message id where the reader will be initially positioned on
* @return the reader builder instance
*/
ReaderBuilder startMessageId(MessageId startMessageId);
/**
* 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.
*
* @param rollbackDuration
* duration which position should be rolled back.
* @return
*/
ReaderBuilder startMessageFromRollbackDuration(long rollbackDuration, TimeUnit timeunit);
/**
* Set the reader to include the given position of {@link ReaderBuilder#startMessageId(MessageId)}
*
* This configuration option also applies for any cursor reset operation like {@link Reader#seek(MessageId)}.
*
* @return the reader builder instance
*/
ReaderBuilder startMessageIdInclusive();
/**
* Sets a {@link ReaderListener} for the reader.
*
* When a {@link ReaderListener} is set, application will receive messages through it. Calls to
* {@link Reader#readNext()} will not be allowed.
*
* @param readerListener
* the listener object
* @return the reader builder instance
*/
ReaderBuilder readerListener(ReaderListener readerListener);
/**
* Sets a {@link CryptoKeyReader} to decrypt the message payloads.
*
* @param cryptoKeyReader
* CryptoKeyReader object
* @return the reader builder instance
*/
ReaderBuilder cryptoKeyReader(CryptoKeyReader cryptoKeyReader);
/**
* Sets the default implementation of {@link CryptoKeyReader}.
*
* Configure the key reader to be used to decrypt the message payloads.
*
* @param privateKey
* the private key that is always used to decrypt message payloads.
* @return the reader builder instance
* @since 2.8.0
*/
ReaderBuilder defaultCryptoKeyReader(String privateKey);
/**
* Sets the default implementation of {@link CryptoKeyReader}.
*
* Configure the key reader to be used to decrypt the message payloads.
*
* @param privateKeys
* the map of private key names and their URIs used to decrypt message payloads.
* @return the reader builder instance
* @since 2.8.0
*/
ReaderBuilder defaultCryptoKeyReader(Map privateKeys);
/**
* Sets the {@link ConsumerCryptoFailureAction} to specify.
*
* @param action
* The action to take when the decoding fails
* @return the reader builder instance
*/
ReaderBuilder cryptoFailureAction(ConsumerCryptoFailureAction action);
/**
* Sets the size of the consumer receive queue.
*
* The consumer receive queue controls how many messages can be accumulated by the {@link Consumer} before the
* application calls {@link Consumer#receive()}. Using a higher value could potentially increase the consumer
* throughput at the expense of bigger memory utilization.
*
*
Default value is {@code 1000} messages and should be good for most use cases.
*
* @param receiverQueueSize
* the new receiver queue size value
* @return the reader builder instance
*/
ReaderBuilder receiverQueueSize(int receiverQueueSize);
/**
* 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.
*
* @param readerName
* the name to use for the reader
* @return the reader builder instance
*/
ReaderBuilder readerName(String readerName);
/**
* Set the subscription role prefix. The default prefix is "reader".
*
* @param subscriptionRolePrefix
* @return the reader builder instance
*/
ReaderBuilder subscriptionRolePrefix(String subscriptionRolePrefix);
/**
* Set the subscription name.
* If subscriptionRolePrefix is set at the same time, this configuration will prevail
*
* @param subscriptionName
* @return the reader builder instance
*/
ReaderBuilder subscriptionName(String subscriptionName);
/**
* 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 {@link PulsarClientException}.
*
* @param readCompacted
* whether to read from the compacted topic
* @return the reader builder instance
*/
ReaderBuilder readCompacted(boolean readCompacted);
/**
* 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.
*
* @param ranges
* key hash ranges for a reader
* @return the reader builder instance
*/
ReaderBuilder keyHashRange(Range... ranges);
}