Class ConsistencySession

java.lang.Object
com.loomcache.server.cp.ConsistencySession
public final class ConsistencySession extends Object
Tracks client session state for session-aware CP primitives.

Purpose: Session-aware primitives like semaphores automatically release resources when a client disconnects. ConsistencySession tracks session lifetime using heartbeat-based expiration, ensuring graceful cleanup of held resources.

Lifecycle:

  • Each client gets a unique sessionId assigned on connection
  • Heartbeats extend the session timeout (prevent expiration)
  • Resources held by expired sessions are automatically released
  • Sessions can be explicitly closed before expiration

Thread Safety: This class is thread-safe. Multiple threads can safely interact with the same session concurrently using volatile fields and atomic counters.

Since:
1.0

  • Constructor Details

    • ConsistencySession

      public ConsistencySession(String sessionId, long sessionTimeoutMs)
      Creates a new ConsistencySession with the given ID and timeout.
      Parameters:
      sessionId - unique session identifier (must not be null or empty)
      sessionTimeoutMs - timeout in milliseconds before auto-expiration (must be positive)
      Throws:
      NullPointerException - if sessionId is null
      IllegalArgumentException - if sessionId is empty or sessionTimeoutMs invalid input: '<'= 0

  • Method Details

    • heartbeat

      public void heartbeat()
      Records a heartbeat from the client, extending the session timeout.

      Each heartbeat updates lastHeartbeatMs, effectively resetting the expiration timer.

      Throws:
      IllegalStateException - if the session is closed or expired

    • isExpired

      public boolean isExpired()
      Checks if the session has expired based on the last heartbeat time.
      Returns:
      true if the session has not received a heartbeat within the timeout window

    • isActive

      public boolean isActive()
      Checks if the session is still active (not closed and not expired).
      Returns:
      true if the session is alive

    • close

      public void close()
      Explicitly closes the session. No further heartbeats are accepted.

    • incrementReferenceCount

      public long incrementReferenceCount()
      Increments the reference count (for tracking held resources).
      Returns:
      the new reference count

    • decrementReferenceCount

      public long decrementReferenceCount()
      Decrements the reference count.
      Returns:
      the new reference count

    • getReferenceCount

      public long getReferenceCount()
      Gets the current reference count (number of resources held).
      Returns:
      the reference count

    • setMetadata

      public void setMetadata(String key, Object value)
      Stores metadata associated with this session.

      Metadata can be used to store client-specific state or context.

      Parameters:
      key - the metadata key (must not be null)
      value - the metadata value (must not be null)
      Throws:
      NullPointerException - if key or value is null

    • getMetadata

      public @Nullable Object getMetadata(String key)
      Retrieves metadata associated with this session.
      Parameters:
      key - the metadata key (must not be null)
      Returns:
      the metadata value, or null if not found (can be null)

    • getTimeSinceLastHeartbeatMs

      public long getTimeSinceLastHeartbeatMs()
      Gets the time since last heartbeat in milliseconds.
      Returns:
      elapsed time since last heartbeat