Class JournalSubscription

java.lang.Object
com.loomcache.server.journal.JournalSubscription
public class JournalSubscription extends Object
Manages a single journal subscription with backpressure and lifecycle control.

Features:

  • Bounded backpressure buffer for entries
  • Subscribe/unsubscribe/pause/resume lifecycle
  • Stats tracking (delivered, pending, lag)
  • Thread-safe operations
Since:
1.0

  • Constructor Details

    • JournalSubscription

      public JournalSubscription(String subscriptionId, EventListener listener, int bufferCapacity)
      Create a new journal subscription.
      Parameters:
      subscriptionId - The unique subscription identifier
      listener - The event listener for this subscription
      bufferCapacity - Capacity of the backpressure buffer
      Throws:
      IllegalArgumentException - if parameters are invalid

  • Method Details

    • offer

      public boolean offer(JournalEntry entry)
      Try to offer an entry to this subscription's buffer.

      Returns false if:

      • The subscription is paused
      • The subscription is closed
      • The buffer is full
      Parameters:
      entry - The entry to offer
      Returns:
      true if successfully added to buffer, false otherwise

    • poll

      public @Nullable JournalEntry poll()
      Poll the next entry from this subscription's buffer without blocking.
      Returns:
      The next entry, or null if buffer is empty

    • markDelivered

      public void markDelivered(JournalEntry entry)
      Mark an entry as delivered and update stats.
      Parameters:
      entry - The delivered entry

    • getLastDeliveredSequence

      public long getLastDeliveredSequence()
      Get the sequence of the last delivered entry.
      Returns:
      last delivered sequence, or -1 if no entries have been delivered

    • isPaused

      public boolean isPaused()
      Check if the subscription is paused.
      Returns:
      true if paused

    • pause

      public void pause()
      Pause this subscription (no new entries will be delivered).

    • resume

      public void resume()
      Resume this subscription.

    • isClosed

      public boolean isClosed()
      Check if the subscription is closed.
      Returns:
      true if closed

    • close

      public void close()
      Close this subscription (permanent; cannot be resumed).

    • getStats

      public SubscriptionStats getStats(long journalLatestSequence)
      Get current subscription statistics.
      Parameters:
      journalLatestSequence - The latest sequence in the journal
      Returns:
      Subscription statistics

    • getPendingCount

      public int getPendingCount()
      Get the current number of pending entries in the buffer.
      Returns:
      Number of pending entries

    • startReplay

      public void startReplay()
      Mark this subscription as replaying. While replaying, live entries are buffered instead of delivered immediately to prevent out-of-order delivery.

    • isReplaying

      public boolean isReplaying()
      Check if this subscription is currently replaying historical entries.
      Returns:
      true if replay is in progress

    • bufferDuringReplay

      public void bufferDuringReplay(JournalEntry entry)
      Buffer a live entry that arrived during replay. These entries will be drained and delivered in order once replay completes.
      Parameters:
      entry - the live entry to buffer

    • completeReplay

      public void completeReplay()
      Mark replay as complete and drain any entries that arrived during replay. Entries are delivered in sequence order to the listener.