org.apache.pulsar.client.api

Interface PulsarClient

All Superinterfaces:

AutoCloseable, Closeable

public interface PulsarClient
extends Closeable

Class that provides a client interface to Pulsar.

Client instances are thread-safe and can be reused for managing multiple Producer, Consumer and Reader instances.

Method Summary

Modifier and Type	Method and Description
static ClientBuilder	builder() Get a new builder instance that can used to configure and build a PulsarClient instance.
void	close() Close the PulsarClient and release all the resources.
CompletableFuture<Void>	closeAsync() Asynchronously close the PulsarClient and release all the resources.
static PulsarClient	create(String serviceUrl) Deprecated. use builder() to construct a client instance
static PulsarClient	create(String serviceUrl, ClientConfiguration conf) Deprecated. use builder() to construct a client instance
Producer<byte[]>	createProducer(String topic) Deprecated. use newProducer() to build a new producer
Producer<byte[]>	createProducer(String topic, ProducerConfiguration conf) Deprecated. use newProducer() to build a new producer
CompletableFuture<Producer<byte[]>>	createProducerAsync(String topic) Deprecated. use newProducer() to build a new producer
CompletableFuture<Producer<byte[]>>	createProducerAsync(String topic, ProducerConfiguration conf) Deprecated. use newProducer() to build a new producer
Reader<byte[]>	createReader(String topic, MessageId startMessageId, ReaderConfiguration conf) Deprecated. Use newReader() to build a new reader
CompletableFuture<Reader<byte[]>>	createReaderAsync(String topic, MessageId startMessageId, ReaderConfiguration conf) Deprecated. Use newReader() to build a new reader
CompletableFuture<List<String>>	getPartitionsForTopic(String topic) Get the list of partitions for a given topic.
ConsumerBuilder<byte[]>	newConsumer() Create a consumer with default for subscribing on a specific topic
<T> ConsumerBuilder<T>	newConsumer(Schema<T> schema) Create a consumer with default for subscribing on a specific topic Since 2.2, if you are creating a consumer with non-bytes schema on a non-existence topic, it will automatically create the topic with the provided schema.
ProducerBuilder<byte[]>	newProducer() Create a producer with default for publishing on a specific topic
<T> ProducerBuilder<T>	newProducer(Schema<T> schema) Create a producer with default for publishing on a specific topic
ReaderBuilder<byte[]>	newReader() Create a topic reader for reading messages from the specified topic.
<T> ReaderBuilder<T>	newReader(Schema<T> schema) Create a topic reader for reading messages from the specified topic.
void	shutdown() Perform immediate shutdown of PulsarClient.
Consumer<byte[]>	subscribe(String topic, String subscription) Deprecated. Use newConsumer() to build a new consumer
Consumer<byte[]>	subscribe(String topic, String subscription, ConsumerConfiguration conf) Deprecated. Use newConsumer() to build a new consumer
CompletableFuture<Consumer<byte[]>>	subscribeAsync(String topic, String subscription) Deprecated. Use newConsumer() to build a new consumer
CompletableFuture<Consumer<byte[]>>	subscribeAsync(String topic, String subscription, ConsumerConfiguration conf) Deprecated. Use newConsumer() to build a new consumer
void	updateServiceUrl(String serviceUrl) Update the service URL this client is using.

Method Detail

builder

static ClientBuilder builder()

Get a new builder instance that can used to configure and build a PulsarClient instance.

Returns:

the ClientBuilder

Since:

2.0.0

create

@Deprecated
static PulsarClient create(String serviceUrl)
                                throws PulsarClientException

Deprecated. use builder() to construct a client instance

Create a new PulsarClient object using default client configuration

Parameters:

serviceUrl - the url of the Pulsar endpoint to be used

Returns:

a new pulsar client object

Throws:

PulsarClientException.InvalidServiceURL - if the serviceUrl is invalid

PulsarClientException

create

@Deprecated
static PulsarClient create(String serviceUrl,
                                       ClientConfiguration conf)
                                throws PulsarClientException

Deprecated. use builder() to construct a client instance

Create a new PulsarClient object

Parameters:

serviceUrl - the url of the Pulsar endpoint to be used

conf - the client configuration

Returns:

a new pulsar client object

Throws:

PulsarClientException.InvalidServiceURL - if the serviceUrl is invalid

PulsarClientException

newProducer

ProducerBuilder<byte[]> newProducer()

Create a producer with default for publishing on a specific topic

Example: Producer producer = client.newProducer().topic(myTopic).create();

Returns:

a ProducerBuilder object to configure and construct the Producer instance

Since:

2.0.0

newProducer

<T> ProducerBuilder<T> newProducer(Schema<T> schema)

Create a producer with default for publishing on a specific topic

Example: Producer producer = client.newProducer(mySchema).topic(myTopic).create();

Parameters:

schema - provide a way to convert between serialized data and domain objects

Returns:

a ProducerBuilder object to configure and construct the Producer instance

Since:

2.0.0

newConsumer

ConsumerBuilder<byte[]> newConsumer()

Create a consumer with default for subscribing on a specific topic

Returns:

a ConsumerBuilder object to configure and construct the Consumer instance

Since:

2.0.0

newConsumer

<T> ConsumerBuilder<T> newConsumer(Schema<T> schema)

Create a consumer with default for subscribing on a specific topic Since 2.2, if you are creating a consumer with non-bytes schema on a non-existence topic, it will automatically create the topic with the provided schema.

Parameters:

schema - provide a way to convert between serialized data and domain objects

Returns:

a ConsumerBuilder object to configure and construct the Consumer instance

Since:

2.0.0

newReader

ReaderBuilder<byte[]> newReader()

Create a topic reader for reading messages from the specified topic.

The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. Reader can only work on non-partitioned topics.

Returns:

a ReaderBuilder that can be used to configure and construct a Reader instance

Since:

2.0.0

newReader

<T> ReaderBuilder<T> newReader(Schema<T> schema)

Create a topic reader for reading messages from the specified topic.

The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. Reader can only work on non-partitioned topics.

Parameters:

schema - provide a way to convert between serialized data and domain objects

Returns:

a ReaderBuilder that can be used to configure and construct a Reader instance

Since:

2.0.0

createProducer

@Deprecated
Producer<byte[]> createProducer(String topic)
                                     throws PulsarClientException

Deprecated. use newProducer() to build a new producer

Create a producer with default ProducerConfiguration for publishing on a specific topic

Parameters:

topic - The name of the topic where to produce

Returns:

The producer object

Throws:

PulsarClientException.AlreadyClosedException - if the client was already closed

PulsarClientException.InvalidTopicNameException - if the topic name is not valid

PulsarClientException.AuthenticationException - if there was an error with the supplied credentials

PulsarClientException.AuthorizationException - if the authorization to publish on topic was denied

PulsarClientException

createProducerAsync

@Deprecated
CompletableFuture<Producer<byte[]>> createProducerAsync(String topic)

Deprecated. use newProducer() to build a new producer

Asynchronously create a producer with default ProducerConfiguration for publishing on a specific topic

Parameters:

topic - The name of the topic where to produce

Returns:

Future of the asynchronously created producer object

createProducer

@Deprecated
Producer<byte[]> createProducer(String topic,
                                            ProducerConfiguration conf)
                                     throws PulsarClientException

Deprecated. use newProducer() to build a new producer

Create a producer with given ProducerConfiguration for publishing on a specific topic

Parameters:

topic - The name of the topic where to produce

conf - The ProducerConfiguration object

Returns:

The producer object

Throws:

PulsarClientException - if it was not possible to create the producer

InterruptedException

createProducerAsync

@Deprecated
CompletableFuture<Producer<byte[]>> createProducerAsync(String topic,
                                                                    ProducerConfiguration conf)

Deprecated. use newProducer() to build a new producer

Asynchronously create a producer with given ProducerConfiguration for publishing on a specific topic

Parameters:

topic - The name of the topic where to produce

conf - The ProducerConfiguration object

Returns:

Future of the asynchronously created producer object

subscribe

@Deprecated
Consumer<byte[]> subscribe(String topic,
                                       String subscription)
                                throws PulsarClientException

Deprecated. Use newConsumer() to build a new consumer

Subscribe to the given topic and subscription combination with default ConsumerConfiguration

Parameters:

topic - The name of the topic

subscription - The name of the subscription

Returns:

The Consumer object

Throws:

PulsarClientException

InterruptedException

subscribeAsync

@Deprecated
CompletableFuture<Consumer<byte[]>> subscribeAsync(String topic,
                                                               String subscription)

Deprecated. Use newConsumer() to build a new consumer

Asynchronously subscribe to the given topic and subscription combination using default ConsumerConfiguration

Parameters:

topic - The topic name

subscription - The subscription name

Returns:

Future of the Consumer object

subscribe

@Deprecated
Consumer<byte[]> subscribe(String topic,
                                       String subscription,
                                       ConsumerConfiguration conf)
                                throws PulsarClientException

Deprecated. Use newConsumer() to build a new consumer

Subscribe to the given topic and subscription combination with given ConsumerConfiguration

Parameters:

topic - The name of the topic

subscription - The name of the subscription

conf - The ConsumerConfiguration object

Returns:

The Consumer object

Throws:

PulsarClientException

subscribeAsync

@Deprecated
CompletableFuture<Consumer<byte[]>> subscribeAsync(String topic,
                                                               String subscription,
                                                               ConsumerConfiguration conf)

Deprecated. Use newConsumer() to build a new consumer

Asynchronously subscribe to the given topic and subscription combination using given ConsumerConfiguration

Parameters:

topic - The name of the topic

subscription - The name of the subscription

conf - The ConsumerConfiguration object

Returns:

Future of the Consumer object

createReader

@Deprecated
Reader<byte[]> createReader(String topic,
                                        MessageId startMessageId,
                                        ReaderConfiguration conf)
                                 throws PulsarClientException

Deprecated. Use newReader() to build a new reader

Create a topic reader with given ReaderConfiguration for reading messages from the specified topic.

The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. Reader can only work on non-partitioned topics.

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 the end topic, only getting messages published after the reader was created
• MessageId : When passing a particular message id, the reader will position itself on that specific position. The first message to be read will be the message next to the specified messageId.

Parameters:

topic - The name of the topic where to read

startMessageId - The message id where the reader will position itself. The first message returned will be the one after the specified startMessageId

conf - The ReaderConfiguration object

Returns:

The Reader object

Throws:

PulsarClientException

createReaderAsync

@Deprecated
CompletableFuture<Reader<byte[]>> createReaderAsync(String topic,
                                                                MessageId startMessageId,
                                                                ReaderConfiguration conf)

Deprecated. Use newReader() to build a new reader

Asynchronously create a topic reader with given ReaderConfiguration for reading messages from the specified topic.

The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. Reader can only work on non-partitioned topics.

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 the end topic, only getting messages published after the reader was created
• MessageId : When passing a particular message id, the reader will position itself on that specific position. The first message to be read will be the message next to the specified messageId.

Parameters:

topic - The name of the topic where to read

startMessageId - The message id where the reader will position itself. The first message returned will be the one after the specified startMessageId

conf - The ReaderConfiguration object

Returns:

Future of the asynchronously created producer object

updateServiceUrl

void updateServiceUrl(String serviceUrl)
               throws PulsarClientException

Update the service URL this client is using. This will force the client close all existing connections and to restart service discovery to the new service endpoint.

Parameters:

serviceUrl - the new service URL this client should connect to

Throws:

PulsarClientException - in case the serviceUrl is not valid

getPartitionsForTopic

CompletableFuture<List<String>> getPartitionsForTopic(String topic)

Get the list of partitions for a given topic. If the topic is partitioned, this will return a list of partition names. If the topic is not partitioned, the returned list will contain the topic name itself. This can be used to discover the partitions and create Reader, Consumer or Producer instances directly on a particular partition.

Parameters:

topic - the topic name

Returns:

a future that will yield a list of the topic partitions

Since:

2.3.0

close

void close()
    throws PulsarClientException

Close the PulsarClient and release all the resources. All the producers and consumers will be orderly closed. Waits until all pending write request are persisted.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

PulsarClientException - if the close operation fails

closeAsync

CompletableFuture<Void> closeAsync()

Asynchronously close the PulsarClient and release all the resources. All the producers and consumers will be orderly closed. Waits until all pending write request are persisted.

Throws:

PulsarClientException - if the close operation fails

shutdown

void shutdown()
       throws PulsarClientException

Perform immediate shutdown of PulsarClient. Release all the resources and close all the producers without waiting for ongoing operations to complete.

Throws:

PulsarClientException - if the forceful shutdown fails