Class NearCacheInvalidationStrategy

java.lang.Object
com.loomcache.client.NearCacheInvalidationStrategy
public class NearCacheInvalidationStrategy extends Object
Strategy for near-cache invalidation with resilience.

Purpose

Handles near-cache invalidation using either server-push (preferred) or TTL-based polling (fallback). If server-push listener registration fails, automatically falls back to periodic polling to ensure near-cache eventually becomes consistent.

Modes

  • PUSH: Server pushes invalidations (low latency, preferred)
  • POLL: Client polls TTL-based invalidations (eventual consistency, fallback)

Failover Logic

When listener registration fails:

  1. Retries with exponential backoff (100ms, 200ms, 400ms, 800ms, 1600ms, 3200ms, 5000ms cap)
  2. After max retries, falls back to polling mode
  3. A gauge metric tracks the current mode for observability

Thread-safe through atomic references and concurrent hash map.

  • Constructor Details

    • NearCacheInvalidationStrategy

      public NearCacheInvalidationStrategy(LoomClient client, long nearCacheTtlMs)
      Create a near-cache invalidation strategy.
      Parameters:
      client - the LoomClient instance (must not be null)
      nearCacheTtlMs - the near cache TTL in milliseconds (0 means infinite)
      Throws:
      NullPointerException - if client is null
      IllegalArgumentException - if nearCacheTtlMs is negative

  • Method Details

    • getCurrentMode

      public NearCacheInvalidationStrategy.InvalidationMode getCurrentMode()
      Get the current invalidation mode. Useful for metrics/observability.
      Returns:
      the current mode (PUSH or POLL, never null)

    • registerListenerWithRetry

      public void registerListenerWithRetry(String mapName, LoomClient.MapChangeListener listener)
      Register a listener for near-cache invalidation with retry resilience.

      If registration fails, retries with exponential backoff. After max retries, the strategy falls back to TTL-based polling.

      Parameters:
      mapName - the map to register for invalidation (must not be null)
      listener - the listener to invoke on invalidation (must not be null)
      Throws:
      NullPointerException - if mapName or listener is null

    • registerMapWithRetry

      public void registerMapWithRetry(String mapName)
      Register the map for server-push near-cache invalidation messages.

    • unregisterListener

      public void unregisterListener(String mapName, LoomClient.MapChangeListener listener)
      Unregister a listener for near-cache invalidation.
      Parameters:
      mapName - the map name (must not be null)
      listener - the listener to unregister (must not be null)
      Throws:
      NullPointerException - if mapName or listener is null

    • unregisterMap

      public void unregisterMap(String mapName)
      Unregister a map from server-push near-cache invalidations.

    • clearRegistrations

      public void clearRegistrations()
      Clear tracked near-cache registrations after connection loss.

      Cancels any pending retry tasks and removes all registration bookkeeping so a later reconnect can re-register near-cache subscriptions cleanly.

    • shutdown

      public void shutdown()
      Shut down the strategy, canceling all retry and poll tasks.

    • onNodeDisconnected

      public void onNodeDisconnected(String nodeId)
      Drop per-node subscription bookkeeping for a connection that just closed.

      Lets the client react to a partial disconnect without wiping registrations for the remaining healthy nodes. Callers should invoke this when the connection count is still greater than zero; a total disconnect should use clearRegistrations() instead so later reconnect starts from a clean slate.

      Parameters:
      nodeId - the node that just disconnected (must not be null)

    • setPollInvalidationCallback

      public void setPollInvalidationCallback(NearCacheInvalidationStrategy.PollInvalidationCallback callback)
      Set the callback for poll-based invalidation. Must be called before registration attempts so the POLL fallback works.
      Parameters:
      callback - the callback to invoke during poll cycles

    • setReconciliationCallback

      public void setReconciliationCallback(NearCacheInvalidationStrategy.ReconciliationCallback callback)

    • configureReconciliation

      public void configureReconciliation(NearCacheReconciliationConfig config)