Package org.apache.pulsar.client.api

Interface PulsarClient

All Superinterfaces:
AutoCloseable, Closeable
@Public @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 Details

    • 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

    • newTableViewBuilder

      @Deprecated <T> TableViewBuilder<T> newTableViewBuilder(Schema<T> schema)
      Deprecated.
      Use newTableView(Schema) to build and configure a TableViewBuilder instance
      Create a table view builder with a specific schema for subscribing on a specific topic.

      The TableView provides a key-value map view of a compacted topic. Messages without keys will be ignored.

      Example: 

      
  TableView<byte[]> tableView = client.newTableViewBuilder(Schema.BYTES)
            .topic("my-topic")
            .autoUpdatePartitionsInterval(5, TimeUnit.SECONDS)
            .create();

  tableView.forEach((k, v) -> System.out.println(k + ":" + v));
      Parameters:
      schema - provide a way to convert between serialized data and domain objects
      Returns:
      a TableViewBuilder object to configure and construct the TableView instance

    • newTableView

      TableViewBuilder<byte[]> newTableView()
      Create a table view builder for subscribing on a specific topic.

      The TableView provides a key-value map view of a compacted topic. Messages without keys will be ignored.

      Example: 

      
  TableView<byte[]> tableView = client.newTableView()
            .topic("my-topic")
            .autoUpdatePartitionsInterval(5, TimeUnit.SECONDS)
            .create();

  tableView.forEach((k, v) -> System.out.println(k + ":" + v));
      Returns:
      a TableViewBuilder object to configure and construct the TableView instance

    • newTableView

      <T> TableViewBuilder<T> newTableView(Schema<T> schema)
      Create a table view builder with a specific schema for subscribing on a specific topic.

      The TableView provides a key-value map view of a compacted topic. Messages without keys will be ignored.

      Example: 

      
  TableView<byte[]> tableView = client.newTableView(Schema.BYTES)
            .topic("my-topic")
            .autoUpdatePartitionsInterval(5, TimeUnit.SECONDS)
            .create();

  tableView.forEach((k, v) -> System.out.println(k + ":" + v));
      Parameters:
      schema - provide a way to convert between serialized data and domain objects
      Returns:
      a TableViewBuilder object to configure and construct the TableView instance

    • 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

      @Deprecated default CompletableFuture<List<String>> getPartitionsForTopic(String topic)
      Deprecated.
      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

    • getPartitionsForTopic

      CompletableFuture<List<String>> getPartitionsForTopic(String topic, boolean metadataAutoCreationEnabled)
      1. Get the partitions if the topic exists. Return "[{partition-0}, {partition-1}....{partition-n}}]" if a partitioned topic exists; return "[{topic}]" if a non-partitioned topic exists. 2. When is "false", neither the partitioned topic nor non-partitioned topic does not exist. You will get an PulsarClientException.NotFoundException or a PulsarClientException.TopicDoesNotExistException. 2-1. You will get a PulsarClientException.NotSupportedException with metadataAutoCreationEnabled=false on an old broker version which does not support getting partitions without partitioned metadata auto-creation. 3. When is "true," it will trigger an auto-creation for this topic(using the default topic auto-creation strategy you set for the broker), and the corresponding result is returned. For the result, see case 1.

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

      Returns:
      a future that can be used to track the completion of the operation

    • 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:

    • 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
      Throws:
      PulsarClientException - if transactions are not enabled
      Since:
      2.7.0