Package org.apache.pulsar.client.api

Interface PulsarClient

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    @Public
@Stable
public interface PulsarClient
extends java.io.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 Detail

      • 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​(java.lang.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

        java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>> getPartitionsForTopic​(java.lang.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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        PulsarClientException - if the close operation fails

      • closeAsync

        java.util.concurrent.CompletableFuture<java.lang.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:
        shutdown(), close(), closeAsync()

      • newTransaction

        TransactionBuilder newTransaction()
                           throws PulsarClientException
        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