Package org.apache.pulsar.client.api.v5

Interface CheckpointConsumer<T>

Type Parameters:
T - the type of message values
All Superinterfaces:
AutoCloseable, Closeable
public interface CheckpointConsumer<T> extends Closeable
An unmanaged consumer designed for connector frameworks (Flink, Spark, etc.).

Unlike StreamConsumer and QueueConsumer, this consumer has no broker-managed subscription — position tracking is entirely external. The connector framework stores checkpoints in its own state backend and uses them to restore on failure.

Internally, the consumer reads from all hash-range segments of a topic. checkpoint() creates an atomic snapshot of positions across all segments, returned as an opaque Checkpoint that can be serialized and stored externally.

This interface provides synchronous (blocking) operations. For non-blocking usage, obtain an AsyncCheckpointConsumer via async().

  • Method Summary

    Modifier and Type
    Method
    Description
    AsyncCheckpointConsumer<T>
    async()
    Return the asynchronous view of this consumer.
    Checkpoint
    checkpoint()
    Create a consistent checkpoint — an atomic snapshot of positions across all internal hash-range segments.
    void
    close()
    Close the consumer and release all resources.
    Message<T>
    receive()
    Receive a single message, blocking indefinitely.
    Message<T>
    receive(Duration timeout)
    Receive a single message, blocking up to the given timeout.
    Messages<T>
    receiveMulti(int maxMessages, Duration timeout)
    Receive a batch of messages, blocking up to the given timeout.
    String
    topic()
    The topic this consumer reads from.

  • Method Details

    • topic

      String topic()
      The topic this consumer reads from.
      Returns:
      the fully qualified topic name

    • receive

      Message<T> receive() throws PulsarClientException
      Receive a single message, blocking indefinitely.
      Returns:
      the received Message
      Throws:
      PulsarClientException - if the consumer is closed or a connection error occurs

    • receive

      Message<T> receive(Duration timeout) throws PulsarClientException
      Receive a single message, blocking up to the given timeout. Returns null if the timeout elapses without a message.
      Parameters:
      timeout - the maximum time to wait for a message
      Returns:
      the received Message, or null if the timeout elapses
      Throws:
      PulsarClientException - if the consumer is closed or a connection error occurs

    • receiveMulti

      Messages<T> receiveMulti(int maxMessages, Duration timeout) throws PulsarClientException
      Receive a batch of messages, blocking up to the given timeout.
      Parameters:
      maxMessages - the maximum number of messages to return
      timeout - the maximum time to wait for messages
      Returns:
      the received Messages batch
      Throws:
      PulsarClientException - if the consumer is closed or a connection error occurs

    • checkpoint

      Checkpoint checkpoint()
      Create a consistent checkpoint — an atomic snapshot of positions across all internal hash-range segments.

      The returned Checkpoint can be serialized via Checkpoint.toByteArray() and stored in the connector framework's state backend.

      Returns:
      an opaque Checkpoint representing the current read positions

    • async

      AsyncCheckpointConsumer<T> async()
      Return the asynchronous view of this consumer.
      Returns:
      the AsyncCheckpointConsumer counterpart of this consumer

    • close

      void close() throws PulsarClientException
      Close the consumer and release all resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      PulsarClientException - if an error occurs while closing the consumer