PulsarClient (Pulsar Client

All Superinterfaces:: AutoCloseable, Closeable

@InterfaceAudience.Public
 @InterfaceStability.Stable
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.

Example of constructing a client:


 PulsarClient client = PulsarClient.builder()
                              .serviceUrl("pulsar://broker:6650")
                              .build();

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
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.
`CompletableFuture<List<String>>`	`getPartitionsForTopic(String topic)` Get the list of partitions for a given topic.
`boolean`	`isClosed()` Return internal state of the client.
`ConsumerBuilder<byte[]>`	`newConsumer()` Create a consumer builder with no schema (`Schema.BYTES`) for subscribing to one or more topics.
`<T> ConsumerBuilder<T>`	`newConsumer(Schema<T> schema)` Create a consumer builder with a specific schema for subscribing on a specific topic
`ProducerBuilder<byte[]>`	`newProducer()` Create a producer builder that can be used to configure and construct a producer with default `Schema.BYTES`.
`<T> ProducerBuilder<T>`	`newProducer(Schema<T> schema)` Create a producer builder that can be used to configure and construct a producer with the specified schema.
`ReaderBuilder<byte[]>`	`newReader()` Create a topic reader builder with no schema (`Schema.BYTES`) to read from the specified topic.
`<T> ReaderBuilder<T>`	`newReader(Schema<T> schema)` Create a topic reader builder with a specific `Schema`) to read from the specified topic.
`TransactionBuilder`	`newTransaction()` Create a transaction builder that can be used to configure and construct a transaction.
`void`	`shutdown()` Perform immediate shutdown of PulsarClient.
`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
  - newProducer
```
ProducerBuilder<byte[]> newProducer()
```
    Create a producer builder that can be used to configure and construct a producer with default Schema.BYTES.
    Example:
```
 Producer<byte[]> producer = client.newProducer()
                  .topic("my-topic")
                  .create();
 producer.send("test".getBytes());
 
```
    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 builder that can be used to configure and construct a producer with the specified schema.
    Example:
```
 Producer<String> producer = client.newProducer(Schema.STRING)
                  .topic("my-topic")
                  .create();
 producer.send("test");
 
```
    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 builder with no schema (Schema.BYTES) for subscribing to one or more topics.
```
 Consumer<byte[]> consumer = client.newConsumer()
        .topic("my-topic")
        .subscriptionName("my-subscription-name")
        .subscribe();

 while (true) {
     Message<byte[]> message = consumer.receive();
     System.out.println("Got message: " + message.getValue());
     consumer.acknowledge(message);
 }
 
```
    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 builder with a specific schema 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.
```
 Consumer<String> consumer = client.newConsumer(Schema.STRING)
        .topic("my-topic")
        .subscriptionName("my-subscription-name")
        .subscribe();

 while (true) {
     Message<String> message = consumer.receive();
     System.out.println("Got message: " + message.getValue());
     consumer.acknowledge(message);
 }
 
```
    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 builder with no schema (Schema.BYTES) to read from the specified topic.
    The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. A reader needs to be specified a ReaderBuilder.startMessageId(MessageId) that can either be:
    - 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
    A Reader can only from non-partitioned topics. In case of partitioned topics, one can create the readers directly on the individual partitions. See getPartitionsForTopic(String) for how to get the topic partitions names.
    Example of usage of Reader:
```
 Reader<byte[]> reader = client.newReader()
        .topic("my-topic")
        .startMessageId(MessageId.earliest)
        .create();

 while (true) {
     Message<byte[]> message = reader.readNext();
     System.out.println("Got message: " + message.getValue());
     // Reader doesn't need acknowledgments
 }
 
```
    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 builder with a specific Schema) to read from the specified topic.
    The Reader provides a low-level abstraction that allows for manual positioning in the topic, without using a subscription. A reader needs to be specified a ReaderBuilder.startMessageId(MessageId) that can either be:
    - 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
    A Reader can only from non-partitioned topics. In case of partitioned topics, one can create the readers directly on the individual partitions. See getPartitionsForTopic(String) for how to get the topic partitions names.
    Example of usage of Reader:
```
 
 Reader<String> reader = client.newReader(Schema.STRING)
        .topic("my-topic")
        .startMessageId(MessageId.earliest)
        .create();

 while (true) {
     Message<String> message = reader.readNext();
     System.out.println("Got message: " + message.getValue());
     // Reader doesn't need acknowledgments
 }
 
```
    Returns:
    
    a ReaderBuilder that can be used to configure and construct a Reader instance
    
    Since:
    
    2.0.0
  - 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 or PulsarClientException if there was any error in the operation.
    
    Since:
    
    2.3.0
  - close
```
void close()
    throws PulsarClientException
```
    Close the PulsarClient and release all the resources.
    This operation will trigger a graceful close of all producer, consumer and reader instances that this client has currently active. That implies that close will block and wait until all pending producer send requests 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.
    This operation will trigger a graceful close of all producer, consumer and reader instances that this client has currently active. That implies that close and wait, asynchronously, until all pending producer send requests 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 producer, consumer and reader instances without waiting for ongoing operations to complete.
    
    Throws:
    
    PulsarClientException - if the forceful shutdown fails
  - isClosed
```
boolean isClosed()
```
    Return internal state of the client. Useful if you want to check that current client is valid.
    
    Returns:
    
    true is the client has been closed
    
    See Also:
    
    shutdown(), close(), closeAsync()
  - newTransaction
```
TransactionBuilder newTransaction()
```
    Create a transaction builder that can be used to configure and construct a transaction.
    Example:
```
 Transaction txn = client.newTransaction()
                         .withTransactionTimeout(1, TimeUnit.MINUTES)
                         .build().get();
 
```
    Returns:
    
    a TransactionBuilder object to configure and construct the Transaction instance
    
    Since:
    
    2.7.0

Interface PulsarClient

Method Summary

Method Detail

builder

newProducer

newProducer

newConsumer

newConsumer

newReader

newReader

updateServiceUrl

getPartitionsForTopic

close

closeAsync

shutdown

isClosed

newTransaction