Package com.salesforce.multicloudj.pubsub.driver

Class AbstractSubscription<T extends AbstractSubscription<T>>

java.lang.Object
com.salesforce.multicloudj.pubsub.driver.AbstractSubscription<T>
All Implemented Interfaces:
Provider, AutoCloseable
public abstract class AbstractSubscription<T extends AbstractSubscription<T>> extends Object implements AutoCloseable, Provider
Abstract base class for subscription implementations.

Implementations should handle proper resource cleanup in the close method, including flushing pending acknowledgments, closing connections, and stopping background threads.

  • Field Details

    • providerId

      protected final String providerId

    • subscriptionName

      protected final String subscriptionName

    • region

      protected final String region

    • endpoint

      protected final URI endpoint

    • proxyEndpoint

      protected final URI proxyEndpoint

    • credentialsOverrider

      protected final CredentialsOverrider credentialsOverrider

    • isShutdown

      protected final AtomicBoolean isShutdown
      Flag indicating whether the subscription has been shut down.

    • permanentError

      protected final AtomicReference<Throwable> permanentError

    • unreportedAckErr

      protected final AtomicReference<Throwable> unreportedAckErr

  • Constructor Details

  • Method Details

    • getProviderId

      public String getProviderId()
      Description copied from interface: Provider
      Retrieves the unique identifier for this provider.
      Specified by:
      getProviderId in interface Provider
      Returns:
      A String representing the provider's ID such as aws.

    • receive

      public Message receive()
      Receives and returns the next message from the Subscription's queue.

      This method provides a simple, blocking interface for consuming messages from a pub/sub subscription. It automatically handles: - Background prefetching to maintain a healthy message queue - Flow control to prevent CPU spinning when no messages are available - Error handling and retry logic for transient failures - Thread-safe concurrent access from multiple threads

      When messages are available, this method returns immediately. When the queue is empty, it will wait for new messages to arrive from the cloud provider, with automatic prefetching happening in the background to keep the queue populated.

      This method can be called concurrently from multiple threads safely.

      Returns:
      the next available message from the subscription
      Throws:
      SubstrateSdkException - if the subscription has been shut down, is in a permanent error state, or if interrupted while waiting for messages

    • doReceiveBatch

      protected abstract List<Message> doReceiveBatch(int batchSize)
      Provider specific implementation must fetch at most batchSize messages from the remote service.

    • createReceiveBatcherOptions

      protected Batcher.Options createReceiveBatcherOptions()
      Creates batcher options for this subscription. Provides defaults that cloud providers can override to provide provider-specific batching configuration that aligns with their service limits and performance characteristics.

    • sendAck

      public void sendAck(AckID ackID)
      Sends acknowledgment for a single message.

      This method enqueues the acknowledgment for batch processing and returns immediately. The actual acknowledgment is sent asynchronously in batches for efficiency.

      Parameters:
      ackID - the acknowledgment identifier

    • sendAcks

      public CompletableFuture<Void> sendAcks(List<AckID> ackIDs)
      Sends acknowledgments for multiple messages.

      The returned Future completes immediately upon enqueueing the acknowledgments for batch processing, without waiting for the underlying RPC to complete.

      Parameters:
      ackIDs - the list of acknowledgment identifiers
      Returns:
      a CompletableFuture that completes when acknowledgments are enqueued

    • sendNack

      public void sendNack(AckID ackID)
      Sends negative acknowledgment for a single message.
      Parameters:
      ackID - the acknowledgment ID to negatively acknowledge
      Throws:
      InvalidArgumentException - if ackID is null
      SubstrateSdkException - if the subscription is in an error state or has been shut down

    • sendNacks

      public CompletableFuture<Void> sendNacks(List<AckID> ackIDs)
      Sends negative acknowledgment for multiple messages.
      Parameters:
      ackIDs - the list of acknowledgment IDs to negatively acknowledge
      Returns:
      a CompletableFuture that completes when the nack is queued
      Throws:
      InvalidArgumentException - if ackIDs is null or contains null elements
      SubstrateSdkException - if the subscription is in an error state or has been shut down

    • canNack

      public abstract boolean canNack()

    • isRetryable

      public abstract boolean isRetryable(Throwable error)

    • getAttributes

      public abstract GetAttributeResult getAttributes()

    • doSendAcks

      protected abstract void doSendAcks(List<AckID> ackIDs)

    • doSendNacks

      protected abstract void doSendNacks(List<AckID> ackIDs)

    • createAckBatcherOptions

      protected abstract Batcher.Options createAckBatcherOptions()

    • close

      public void close() throws Exception
      Implements AutoCloseable interface for try-with-resources support.

      Shuts down the subscription and releases all resources.

      This method should: - Flush any pending acknowledgments or nacks - Close network connections - Release any other provider-specific resources

      After calling this method, the subscription should not accept new operations. It is safe to call this method multiple times.

      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception

    • getException

      public abstract Class<? extends SubstrateSdkException> getException(Throwable t)
      Description copied from interface: Provider
      Maps a given Throwable from the provider implementation to a specific SubstrateSdkException. This is used for exception handling abstraction.
      Specified by:
      getException in interface Provider
      Parameters:
      t - The Throwable to be mapped.
      Returns:
      The Class of the corresponding SubstrateSdkException.