Class TtlManager

java.lang.Object
com.loomcache.server.lease.TtlManager
public class TtlManager extends Object
Centralized manager for TTL (Time-To-Live) policies across all distributed cache data structures.

Supports multiple TTL policies (fixed, sliding, adaptive, per-key, eternal) and coordinates expiration across different data structures. Uses an ExpirationScheduler for efficient background expiration processing.

Features:

  • Set TTL policy per data structure
  • Per-key TTL override for PerKeyTtl policies
  • Get remaining TTL for any key
  • Touch operation for sliding TTL reset
  • Event listener support for expiration and TTL changes
  • Background expiration processing (configurable interval)
  • Statistics tracking: total managed, total expired, avg/min TTL
  • Thread-safe with ReentrantLock for complex operations
Since:
1.5

  • Constructor Details

    • TtlManager

      public TtlManager(long scanIntervalMs, Consumer<ExpirationTask> onExpiration)
      Creates a new TtlManager with configurable scan interval.
      Parameters:
      scanIntervalMs - interval in milliseconds between expiration scans (default 1000)
      onExpiration - callback for expired tasks

    • TtlManager

      public TtlManager(Consumer<ExpirationTask> onExpiration)
      Creates a new TtlManager with default 1-second scan interval.
      Parameters:
      onExpiration - callback for expired tasks

  • Method Details

    • setPolicyForDataStructure

      public void setPolicyForDataStructure(String dsName, TtlPolicy policy)
      Sets the TTL policy for a data structure.

      All entries in this data structure will follow the specified policy, unless overridden by per-key TTL settings.

      Parameters:
      dsName - the data structure name (e.g., "users")
      policy - the TTL policy to apply
      Throws:
      NullPointerException - if dsName or policy is null

    • setTtl

      public void setTtl(String dsName, String key, Duration ttl)
      Sets the TTL for a specific key.

      This is used to override the data structure's default policy for a single key. Only applies if the data structure uses PerKeyTtl policy.

      Parameters:
      dsName - the data structure name
      key - the cache key
      ttl - the time-to-live duration
      Throws:
      NullPointerException - if dsName, key, or ttl is null

    • getRemainingTtl

      public Optional<Duration> getRemainingTtl(String dsName, String key)
      Gets the remaining TTL for a key.
      Parameters:
      dsName - the data structure name
      key - the cache key
      Returns:
      Optional containing remaining TTL, or empty if no expiry or key not found

    • touch

      public void touch(String dsName, String key)
      Touches a key to reset its sliding TTL.

      Updates the lastAccessedAtNano timestamp. For SlidingTtl policies, this effectively resets the expiration countdown.

      Parameters:
      dsName - the data structure name
      key - the cache key

    • expireNow

      public boolean expireNow(String dsName, String key)
      Immediately expires a key.

      Removes the key from TTL tracking and notifies listeners.

      Parameters:
      dsName - the data structure name
      key - the cache key
      Returns:
      true if the key was expired, false if not found

    • getExpiredEntries

      public List<String> getExpiredEntries(String dsName)
      Gets all expired keys for a data structure.

      This scans the TTL metadata and identifies keys whose absolute expiration deadline has elapsed. Note: keys are not automatically removed; this method provides a list for explicit cleanup.

      Parameters:
      dsName - the data structure name
      Returns:
      list of expired keys

    • addListener

      public void addListener(TtlEventListener listener)
      Registers a TTL event listener.
      Parameters:
      listener - the listener to register

    • removeListener

      public void removeListener(TtlEventListener listener)
      Unregisters a TTL event listener.
      Parameters:
      listener - the listener to remove

    • start

      public void start()
      Starts background expiration processing.

    • shutdown

      public void shutdown()
      Stops background expiration processing.

    • isRunning

      public boolean isRunning()
      Gets whether the manager is running.
      Returns:
      true if background processing is active

    • getStats

      public TtlManager.TtlStats getStats()
      Gets statistics about TTL management.
      Returns:
      TtlStats record with current statistics