Package com.hazelcast.cp.session

Interface CPSession

public interface CPSession
Represents a CP session.

For CP data structures that involve resource ownership management, such as locks or semaphores, sessions are required to keep track of liveliness of callers. In this context, "caller" means an entity that uses CP Subsystem APIs. It can be either a Hazelcast server or client. A caller initially creates a session before sending its very first session-based request to a CP group, such as a lock / semaphore acquire. After creating a session on the CP group, the caller stores its session id locally and sends it alongside its session-based operations. A single session is used for all lock and semaphore proxies of the caller. When a CP group receives a session-based operation, it checks the validity of the session using the session id information available in the operation. A session is valid if it is still open in the CP group. An operation with a valid session id is accepted as a new session heartbeat. While a caller is idle, in other words, it does not send any session-based operation to the CP group for a while, it commits periodic heartbeats to the CP group in the background in order to keep its session alive. This interval is specified in CPSubsystemConfig.getSessionHeartbeatIntervalSeconds().

A session is closed when the caller does not touch the session during a predefined duration. In this case, the caller is assumed to be crashed and all its resources are released automatically. This duration is specified in CPSubsystemConfig.getSessionTimeToLiveSeconds(). Please check CPSubsystemConfig for recommendations to choose a reasonable session time-to-live duration.

Sessions offer a trade-off between liveliness and safety. If a very small value is set to CPSubsystemConfig.setSessionTimeToLiveSeconds(int), then a session owner could be considered crashed very quickly and its resources can be released prematurely. On the other hand, if a large value is set, a session could be kept alive for an unnecessarily long duration even if its owner actually crashes. However, it is a safer approach to not to use a small session time to live duration. If a session owner is known to be crashed, its session could be closed manually via CPSessionManagementService.forceCloseSession(String, long).

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    CPSession.CPSessionOwnerType
    Represents type of endpoints that create CP sessions

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    creationTime()
    Returns the timestamp of when the session was created
    Address
    endpoint()
    Returns the endpoint that has created this session
    String
    endpointName()
    Returns name of the endpoint that has created this session
    CPSession.CPSessionOwnerType
    endpointType()
    Returns type of the endpoint that has created this session
    long
    expirationTime()
    Returns the timestamp of when the session will expire
    long
    id()
    Returns id of the session
    boolean
    isExpired(long timestamp)
    Returns true if the session expires before the given timestamp.
    long
    version()
    Returns version of the session.

  • Method Details

    • id

      long id()
      Returns id of the session

    • creationTime

      long creationTime()
      Returns the timestamp of when the session was created

    • expirationTime

      long expirationTime()
      Returns the timestamp of when the session will expire

    • version

      long version()
      Returns version of the session. A session's version is incremented on each heartbeat.

    • isExpired

      boolean isExpired(long timestamp)
      Returns true if the session expires before the given timestamp.

    • endpoint

      Address endpoint()
      Returns the endpoint that has created this session

    • endpointType

      CPSession.CPSessionOwnerType endpointType()
      Returns type of the endpoint that has created this session

    • endpointName

      String endpointName()
      Returns name of the endpoint that has created this session