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

Interface StreamConsumer<T>

Type Parameters:
T - the type of message values
All Superinterfaces:
AutoCloseable, Closeable
public interface StreamConsumer<T> extends Closeable
A consumer for streaming (ordered) consumption with broker-managed position tracking.

Messages are delivered in order (per-key if keyed). Acknowledgment is cumulative only: acknowledging a message ID means all messages up to and including that ID are acknowledged.

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

This maps to the Exclusive/Failover subscription model in the Pulsar v4 API.

  • Method Details

    • topic

      String topic()
      The topic this consumer is subscribed to.
      Returns:
      the fully qualified topic name

    • subscription

      String subscription()
      The subscription name.
      Returns:
      the subscription name

    • consumerName

      String consumerName()
      The consumer name (system-assigned or user-specified).
      Returns:
      the consumer name, never null

    • 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 maxNumMessages, Duration timeout) throws PulsarClientException
      Receive a batch of messages, blocking up to the given timeout.
      Parameters:
      maxNumMessages - 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

    • acknowledgeCumulative

      void acknowledgeCumulative(MessageId messageId)
      Acknowledge all messages up to and including the given message ID.
      Parameters:
      messageId - the ID of the message to acknowledge cumulatively

    • acknowledgeCumulative

      void acknowledgeCumulative(MessageId messageId, Transaction txn)
      Acknowledge within a transaction. The acknowledgment becomes effective when the transaction is committed.
      Parameters:
      messageId - the ID of the message to acknowledge cumulatively
      txn - the transaction to associate the acknowledgment with

    • async

      AsyncStreamConsumer<T> async()
      Return the asynchronous view of this consumer.
      Returns:
      the AsyncStreamConsumer 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