io.atomix.copycat.server.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, Copycat 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.

Author:

Method Summary

Modifier and Type	Method and Description
void	close(ServerSession session) Called when a session was closed.
void	expire(ServerSession session) Called when a session is expired by the system.
void	register(ServerSession session) Called when a new session is registered.
void	unregister(ServerSession session) Called when a session is unregistered by the client.

Method Detail

register

void register(ServerSession 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 register(Session 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 ServerSession.publish(String, Object) session events to this session.

unregister

void unregister(ServerSession session)

Called when a session is unregistered by the client.

This method is called only when a client explicitly unregisters its session by closing it. In other words, calls to this method indicate that the session was closed by the client rather than expired by a server. This method will always be called for a given session before close(ServerSession), and close(ServerSession) will always be called following this method.

State machines are free to ServerSession.publish(String, Object) session event messages to any session except the one being unregistered. Session event messages sent to the session being unregistered will be lost since the session is closed once this method call completes.

Parameters:

session - The session that was unregistered. State machines cannot ServerSession.publish(String, Object) session events to this session.

expire

void expire(ServerSession 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 close(ServerSession), and close(ServerSession) will always be called following this method.

State machines are free to ServerSession.publish(String, Object) 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 ServerSession.publish(String, Object) session events to this session.

close

void close(ServerSession session)

Called when a session was closed.

This method is called after a ServerSession is either unregistered or expired. State machines can implement this method to react to any session being removed from memory. This method will always be called for a specific session after either unregister(ServerSession) or expire(ServerSession), and one of those methods will always be called before this method.

State machines are free to ServerSession.publish(String, Object) 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 ServerSession.publish(String, Object) session events to this session.