程序包 org.apache.pulsar.client.api

接口 PulsarClient

  • 所有超级接口:
    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();

    • 方法概要

      所有方法 静态方法 实例方法 抽象方法 
      修饰符和类型 方法 说明
      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.
      java.util.concurrent.CompletableFuture<java.lang.Void> closeAsync()
      Asynchronously close the PulsarClient and release all the resources.
      java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>> getPartitionsForTopic​(java.lang.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​(java.lang.String serviceUrl)
      Update the service URL this client is using.

    • 方法详细资料

      • 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());
        返回:
        a ProducerBuilder object to configure and construct the Producer instance
        从以下版本开始:
        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");
        参数:
        schema - provide a way to convert between serialized data and domain objects
        返回:
        a ProducerBuilder object to configure and construct the Producer instance
        从以下版本开始:
        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);
 }
        返回:
        a ConsumerBuilder object to configure and construct the Consumer instance
        从以下版本开始:
        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);
 }
        参数:
        schema - provide a way to convert between serialized data and domain objects
        返回:
        a ConsumerBuilder object to configure and construct the Consumer instance
        从以下版本开始:
        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
 }
        返回:
        a ReaderBuilder that can be used to configure and construct a Reader instance
        从以下版本开始:
        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
 }
        返回:
        a ReaderBuilder that can be used to configure and construct a Reader instance
        从以下版本开始:
        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.

        参数:
        serviceUrl - the new service URL this client should connect to
        抛出:
        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.

        参数:
        topic - the topic name
        返回:
        a future that will yield a list of the topic partitions or PulsarClientException if there was any error in the operation.
        从以下版本开始:
        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.

        指定者:
        close 在接口中 java.lang.AutoCloseable
        指定者:
        close 在接口中 java.io.Closeable
        抛出:
        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.

        抛出:
        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.

        抛出:
        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.
        返回:
        true is the client has been closed
        另请参阅:
        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();
        返回:
        a TransactionBuilder object to configure and construct the Transaction instance
        抛出:
        PulsarClientException - if transactions are not enabled
        从以下版本开始:
        2.7.0