Package org.apache.pulsar.client.api

Interface Reader<T>

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    @Public
@Stable
public interface Reader<T>
extends java.io.Closeable
    A Reader can be used to scan through all the messages currently available in a topic.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.concurrent.CompletableFuture<java.lang.Void> closeAsync()
      Asynchronously close the reader and stop the broker to push more messages.
      java.lang.String getTopic()  
      boolean hasMessageAvailable()
      Check if there is any message available to read from the current position.
      java.util.concurrent.CompletableFuture<java.lang.Boolean> hasMessageAvailableAsync()
      Asynchronously check if there is any message available to read from the current position.
      boolean hasReachedEndOfTopic()
      Return true if the topic was terminated and this reader has reached the end of the topic.
      boolean isConnected()  
      Message<T> readNext()
      Read the next message in the topic.
      Message<T> readNext​(int timeout, java.util.concurrent.TimeUnit unit)
      Read the next message in the topic waiting for a maximum time.
      java.util.concurrent.CompletableFuture<Message<T>> readNextAsync()
      Read asynchronously the next message in the topic.
      void seek​(long timestamp)
      Reset the subscription associated with this reader to a specific message publish time.
      void seek​(java.util.function.Function<java.lang.String,​java.lang.Object> function)
      Reset the subscription associated with this consumer to a specific message ID or message publish time.
      void seek​(MessageId messageId)
      Reset the subscription associated with this reader to a specific message id.
      java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(long timestamp)
      Reset the subscription associated with this reader to a specific message publish time.
      java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(java.util.function.Function<java.lang.String,​java.lang.Object> function)
      Reset the subscription associated with this consumer to a specific message ID or message publish time asynchronously.
      java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(MessageId messageId)
      Reset the subscription associated with this reader to a specific message id.

      • Methods inherited from interface java.io.Closeable

        close

    • Method Detail

      • getTopic

        java.lang.String getTopic()
        Returns:
        the topic from which this reader is reading from

      • readNext

        Message<T> readNext​(int timeout,
                    java.util.concurrent.TimeUnit unit)
             throws PulsarClientException
        Read the next message in the topic waiting for a maximum time.

        Returns null if no message is received before the timeout.

        Returns:
        the next message(Could be null if none received in time)
        Throws:
        PulsarClientException

      • readNextAsync

        java.util.concurrent.CompletableFuture<Message<T>> readNextAsync()
        Read asynchronously the next message in the topic.

        readNextAsync() should be called subsequently once returned CompletableFuture gets complete with received message. Else it creates backlog of receive requests in the application.

        The returned future can be cancelled before completion by calling .cancel(false) (CompletableFuture.cancel(boolean)) to remove it from the the backlog of receive requests. Another choice for ensuring a proper clean up of the returned future is to use the CompletableFuture.orTimeout method which is available on JDK9+. That would remove it from the backlog of receive requests if receiving exceeds the timeout.

        Returns:
        a future that will yield a message (when it's available) or PulsarClientException if the reader is already closed.

      • closeAsync

        java.util.concurrent.CompletableFuture<java.lang.Void> closeAsync()
        Asynchronously close the reader and stop the broker to push more messages.
        Returns:
        a future that can be used to track the completion of the operation

      • hasReachedEndOfTopic

        boolean hasReachedEndOfTopic()
        Return true if the topic was terminated and this reader has reached the end of the topic.

        Note that this only applies to a "terminated" topic (where the topic is "sealed" and no more messages can be published) and not just that the reader is simply caught up with the publishers. Use hasMessageAvailable() to check for for that.

      • hasMessageAvailable

        boolean hasMessageAvailable()
                     throws PulsarClientException
        Check if there is any message available to read from the current position.

        This check can be used by an application to scan through a topic and stop when the reader reaches the current last published message. For example: 

        
 while (reader.hasMessageAvailable()) {
     Message<String> msg = reader.readNext();
     // Do something
 }

 // Done reading

        Note that this call might be blocking (see hasMessageAvailableAsync() for async version) and that even if this call returns true, that will not guarantee that a subsequent call to readNext() will not block.

        Returns:
        true if the are messages available to be read, false otherwise
        Throws:
        PulsarClientException - if there was any error in the operation

      • hasMessageAvailableAsync

        java.util.concurrent.CompletableFuture<java.lang.Boolean> hasMessageAvailableAsync()
        Asynchronously check if there is any message available to read from the current position.

        This check can be used by an application to scan through a topic and stop when the reader reaches the current last published message.

        Returns:
        a future that will yield true if the are messages available to be read, false otherwise, or a PulsarClientException if there was any error in the operation

      • isConnected

        boolean isConnected()
        Returns:
        Whether the reader is connected to the broker

      • seek

        void seek​(MessageId messageId)
   throws PulsarClientException
        Reset the subscription associated with this reader to a specific message id.

        The message id can either be a specific message or represent the first or last messages in the topic.

        • MessageId.earliest : Reset the reader on the earliest message available in the topic
        • MessageId.latest : Reset the reader on the latest message in the topic

        Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

        Parameters:
        messageId - the message id where to reposition the reader
        Throws:
        PulsarClientException

      • seek

        void seek​(long timestamp)
   throws PulsarClientException
        Reset the subscription associated with this reader to a specific message publish time.

        Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

        Parameters:
        timestamp - the message publish time where to reposition the reader
        Throws:
        PulsarClientException

      • seek

        void seek​(java.util.function.Function<java.lang.String,​java.lang.Object> function)
   throws PulsarClientException
        Reset the subscription associated with this consumer to a specific message ID or message publish time.

        The Function input is topic+partition. It returns only timestamp or MessageId.

        The return value is the seek position/timestamp of the current partition. Exception is thrown if other object types are returned.

        If returns null, the current partition will not do any processing. Exception in a partition may affect other partitions.

        Parameters:
        function -
        Throws:
        PulsarClientException

      • seekAsync

        java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(java.util.function.Function<java.lang.String,​java.lang.Object> function)
        Reset the subscription associated with this consumer to a specific message ID or message publish time asynchronously.

        The Function input is topic+partition. It returns only timestamp or MessageId.

        The return value is the seek position/timestamp of the current partition. Exception is thrown if other object types are returned.

        If returns null, the current partition will not do any processing. Exception in a partition may affect other partitions.

        Parameters:
        function -
        Returns:

      • seekAsync

        java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(MessageId messageId)
        Reset the subscription associated with this reader to a specific message id.

        The message id can either be a specific message or represent the first or last messages in the topic.

        • MessageId.earliest : Reset the reader on the earliest message available in the topic
        • MessageId.latest : Reset the reader on the latest message in the topic

        Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

        Parameters:
        messageId - the message id where to position the reader
        Returns:
        a future to track the completion of the seek operation

      • seekAsync

        java.util.concurrent.CompletableFuture<java.lang.Void> seekAsync​(long timestamp)
        Reset the subscription associated with this reader to a specific message publish time.

        Note: this operation can only be done on non-partitioned topics. For these, one can rather perform the seek() on the individual partitions.

        Parameters:
        timestamp - the message publish time where to position the reader
        Returns:
        a future to track the completion of the seek operation