Package io.atomix.primitive.session

Interface SessionListener

public interface SessionListener
Support for listening for state changes in server sessions.

When implemented by a StateMachine, this interface provides support to state machines for reacting to changes in the sessions connected to the cluster. State machines can react to clients registering and unregistering sessions and servers expiring sessions.

Sessions represent a single client's open connection to a cluster. Within the context of a session, Raft provides additional guarantees for clients like linearizability for writes and sequential consistency for reads. Additionally, state machines can push messages to specific clients via sessions. Typically, all state machines that rely on session-based messaging should implement this interface to track when a session is closed.

  • Method Summary

    Modifier and Type Method Description
    void onClose​(Session session)
    Called when a session was closed by the client.
    void onExpire​(Session session)
    Called when a session is expired by the system.
    void onOpen​(Session session)
    Called when a new session is registered.

  • Method Details

    • onOpen

      void onOpen​(Session session)
      Called when a new session is registered.

      A session is registered when a new client connects to the cluster or an existing client recovers its session after being partitioned from the cluster. It's important to note that when this method is called, the Session is not yet open and so events cannot be published to the registered session. This is because clients cannot reliably track messages pushed from server state machines to the client until the session has been fully registered. Session event messages may still be published to other already-registered sessions in reaction to a session being registered.

      To push session event messages to a client through its session upon registration, state machines can use an asynchronous callback or schedule a callback to send a message. 

         
   public void onOpen(RaftSession session) {
     executor.execute(() -> session.publish("foo", "Hello world!"));
   }
      Sending a session event message in an asynchronous callback allows the server time to register the session and notify the client before the event message is sent. Published event messages sent via this method will be sent the next time an operation is applied to the state machine.
      Parameters:
      session - The session that was registered. State machines cannot Session.publish(PrimitiveEvent) session events to this session.

    • onExpire

      void onExpire​(Session session)
      Called when a session is expired by the system.

      This method is called when a client fails to keep its session alive with the cluster. If the leader hasn't heard from a client for a configurable time interval, the leader will expire the session to free the related memory. This method will always be called for a given session before onClose(Session), and onClose(Session) will always be called following this method.

      State machines are free to Session.publish(PrimitiveEvent) session event messages to any session except the one that expired. Session event messages sent to the session that expired will be lost since the session is closed once this method call completes.

      Parameters:
      session - The session that was expired. State machines cannot Session.publish(PrimitiveEvent) session events to this session.

    • onClose

      void onClose​(Session session)
      Called when a session was closed by the client.

      This method is called when a client explicitly closes a session.

      State machines are free to Session.publish(PrimitiveEvent) session event messages to any session except the one that was closed. Session event messages sent to the session that was closed will be lost since the session is closed once this method call completes.

      Parameters:
      session - The session that was closed. State machines cannot Session.publish(PrimitiveEvent) session events to this session.