Class NearCacheInvalidationManager

java.lang.Object
com.loomcache.server.cache.NearCacheInvalidationManager
public class NearCacheInvalidationManager extends Object
Manages near-cache invalidation subscriptions and broadcasts.

Clients with near-caching enabled subscribe to map-level invalidation events. When a key is modified (PUT, DELETE, CLEAR) on the server, this manager broadcasts a MessageType.NEAR_CACHE_INVALIDATE message to all subscribed clients so they can evict stale entries immediately rather than waiting for TTL expiry.

Thread-safe: uses ConcurrentHashMap for tracking structures and a shared lock to keep forward and reverse subscription indices consistent.

Since:
1.3

  • Constructor Details

    • NearCacheInvalidationManager

      public NearCacheInvalidationManager(TcpServer tcpServer)
      Initialize near-cache invalidation manager.
      Parameters:
      tcpServer - the TCP server for broadcasting messages (must not be null)

  • Method Details

    • subscribe

      public void subscribe(String peerId, String mapName)
      Subscribe a client to invalidation events for a specific map.
      Parameters:
      peerId - the subscribing client's peer ID (must not be null)
      mapName - the map to watch for invalidations (must not be null)

    • unsubscribe

      public void unsubscribe(String peerId, String mapName)
      Unsubscribe a client from invalidation events for a specific map.
      Parameters:
      peerId - the client's peer ID (must not be null)
      mapName - the map to stop watching (must not be null)

    • unsubscribeAll

      public void unsubscribeAll(String peerId)
      Unsubscribe a client from all maps. Called on connection close.
      Parameters:
      peerId - the disconnecting client's peer ID (must not be null)

    • deregisterMap

      public void deregisterMap(String mapName)
      Remove all invalidation state for a map when the map is destroyed.
      Parameters:
      mapName - the destroyed map name (must not be null)

    • broadcastInvalidation

      public void broadcastInvalidation(String mapName, @Nullable String key)
      Broadcast an invalidation event to all clients subscribed to the given map. Called after MAP_PUT, MAP_DELETE, MAP_CLEAR, etc.

      Each invalidation carries a per-map monotonic sequence number in the message value (8-byte big-endian long). Clients use this to detect duplicates, out-of-order delivery, and sequence gaps.

      Sends asynchronously on virtual threads without blocking the caller, while preserving enqueue order relative to sequence assignment.

      Parameters:
      mapName - the map that was modified
      key - the key that was modified (null for CLEAR operations)

    • getMapSequence

      public long getMapSequence(String mapName)
      Get the current sequence number for a map. Useful for diagnostics and testing.
      Parameters:
      mapName - the map name
      Returns:
      the current sequence, or 0 if no invalidations have been broadcast

    • getTotalInvalidationsSent

      public long getTotalInvalidationsSent()

    • getTotalInvalidationsFailed

      public long getTotalInvalidationsFailed()

    • getSubscriptionCount

      public int getSubscriptionCount()

    • getSubscribedPeerCount

      public int getSubscribedPeerCount()

    • getSubscriptions

      public Map<String, Set<String>> getSubscriptions()
      Get a snapshot of all subscriptions for diagnostics.