Class EventJournal

java.lang.Object
com.loomcache.server.journal.EventJournal
public class EventJournal extends Object
Distributed event journal for durable, ordered event sourcing.

Features:

  • Monotonically increasing sequence numbers for ordering
  • Thread-safe append and read operations
  • Query by key, event type, or both
  • Real-time subscription with backpressure
  • Configurable overflow policies (DROP_OLDEST, BLOCK, REJECT)
  • Comprehensive statistics tracking

Thread safety: All operations are protected by ReentrantReadWriteLock for consistent views and atomic transactions.

Since:
1.0

  • Constructor Details

    • EventJournal

      public EventJournal(String journalName, int capacity, EventJournal.OverflowPolicy overflowPolicy, int subscriptionBufferCapacity)
      Create an event journal with custom configuration.
      Parameters:
      journalName - The name of this journal
      capacity - Maximum number of entries
      overflowPolicy - Overflow behavior at capacity
      subscriptionBufferCapacity - Buffer size for each subscription
      Throws:
      IllegalArgumentException - if parameters are invalid

  • Method Details

    • append

      public long append(String eventType, String key, byte[] payload, Map<String,String> metadata)
      Append a new event to the journal.
      Parameters:
      eventType - The event type classifier
      key - Associated key (use empty string if no key)
      payload - Event payload as bytes
      metadata - Event metadata
      Returns:
      The sequence number assigned to this entry
      Throws:
      IllegalStateException - if overflow policy is REJECT and journal is full

    • read

      public List<JournalEntry> read(long fromSequence, int maxCount)
      Read entries from a starting sequence.
      Parameters:
      fromSequence - Starting sequence (inclusive)
      maxCount - Maximum entries to return
      Returns:
      List of entries (may be smaller than maxCount)

    • readByKey

      public List<JournalEntry> readByKey(String key, long fromSequence, int maxCount)
      Read entries filtered by key.
      Parameters:
      key - The key to filter by
      fromSequence - Starting sequence (inclusive)
      maxCount - Maximum entries to return
      Returns:
      List of entries matching the key

    • readByEventType

      public List<JournalEntry> readByEventType(String eventType, long fromSequence, int maxCount)
      Read entries filtered by event type.
      Parameters:
      eventType - The event type to filter by
      fromSequence - Starting sequence (inclusive)
      maxCount - Maximum entries to return
      Returns:
      List of entries matching the event type

    • getLatestSequence

      public long getLatestSequence()
      Get the latest sequence number in the journal.
      Returns:
      The latest sequence, or -1 if empty

    • getOldestSequence

      public long getOldestSequence()
      Get the oldest sequence number in the journal.
      Returns:
      The oldest sequence, or -1 if empty

    • subscribe

      public String subscribe(long fromSequence, EventListener listener)
      Subscribe to journal events starting from a sequence.

      Returns immediately. The subscription will receive entries asynchronously via the listener callback.

      Parameters:
      fromSequence - The starting sequence
      listener - The event listener
      Returns:
      The subscription ID (can be used to manage the subscription)

    • unsubscribe

      public void unsubscribe(String subscriptionId)
      Unsubscribe from the journal.
      Parameters:
      subscriptionId - The subscription ID

    • pauseSubscription

      public void pauseSubscription(String subscriptionId)
      Pause a subscription.
      Parameters:
      subscriptionId - The subscription ID

    • resumeSubscription

      public void resumeSubscription(String subscriptionId)
      Resume a paused subscription.
      Parameters:
      subscriptionId - The subscription ID

    • getSubscriptionStats

      public @Nullable SubscriptionStats getSubscriptionStats(String subscriptionId)
      Get statistics for a specific subscription.
      Parameters:
      subscriptionId - The subscription ID
      Returns:
      Subscription statistics, or null if not found

    • getStats

      public JournalStats getStats()
      Get overall journal statistics.
      Returns:
      Journal statistics

    • compact

      public int compact(RetentionPolicy policy)
      Compact the journal based on a retention policy.

      Removes entries that do not pass the retention policy check. This is typically called periodically or in response to storage constraints.

      Parameters:
      policy - The retention policy to apply
      Returns:
      Number of entries removed

    • clear

      public void clear()
      Clear all entries from the journal.

      This is a destructive operation and resets statistics.

    • size

      public int size()
      Get the current number of entries.
      Returns:
      Current size

    • getSubscriptionCount

      public int getSubscriptionCount()
      Get active subscription count.
      Returns:
      Number of active subscriptions