Package com.salesforce.multicloudj.pubsub.driver

Class AbstractSubscription<T extends AbstractSubscription<T>>

  • All Implemented Interfaces:
    AutoCloseable
    Direct Known Subclasses:
    GcpSubscription
    public abstract class AbstractSubscription<T extends AbstractSubscription<T>>
extends Object
implements AutoCloseable
    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 Detail

      • 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

      • receiveTimeoutSeconds

        protected final long receiveTimeoutSeconds

      • isShutdown

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

    • Method Detail

      • getProviderId

        public String getProviderId()

      • 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)

      • doSendAcks

        protected abstract void doSendAcks​(List<AckID> ackIDs)

      • doSendNacks

        protected abstract void doSendNacks​(List<AckID> ackIDs)

      • validateAckIDType

        protected void validateAckIDType​(AckID ackID)

      • 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