io.aeron.cluster.service

Interface ClusteredService

All Known Implementing Classes:

BasicAuctionClusteredService

public interface ClusteredService

Interface which a service must implement to be contained in the cluster.

The cluster object should only be used to send messages to the cluster or schedule timers in response to other messages and timers. Sending messages and timers should not happen from cluster lifecycle methods like onStart(Cluster, Image), onRoleChange(Cluster.Role) or onTakeSnapshot(ExclusivePublication), or onTerminate(Cluster), with the exception of the session lifecycle methods.

Method Summary

Modifier and Type	Method and Description
default void	onNewLeadershipTermEvent(long leadershipTermId, long logPosition, long timestamp, long termBaseLogPosition, int leaderMemberId, int logSessionId, TimeUnit timeUnit, int appVersion) An election has been successful and a leader has entered a new term.
void	onRoleChange(Cluster.Role newRole) Notify that the cluster node has changed role.
void	onSessionClose(ClientSession session, long timestamp, CloseReason closeReason) A session has been closed for a client to the cluster.
void	onSessionMessage(ClientSession session, long timestamp, DirectBuffer buffer, int offset, int length, Header header) A message has been received to be processed by a clustered service.
void	onSessionOpen(ClientSession session, long timestamp) A session has been opened for a client to the cluster.
void	onStart(Cluster cluster, Image snapshotImage) Start event for the service where the service can perform any initialisation required and load snapshot state.
void	onTakeSnapshot(ExclusivePublication snapshotPublication) The service should take a snapshot and store its state to the provided archive Publication.
void	onTerminate(Cluster cluster) Called when the container is going to terminate.
void	onTimerEvent(long correlationId, long timestamp) A scheduled timer has expired.

Method Detail

onStart

void onStart(Cluster cluster,
             Image snapshotImage)

Start event for the service where the service can perform any initialisation required and load snapshot state. The snapshot image can be null if no previous snapshot exists.

Note: As this is a potentially long running operation the implementation should use Cluster.idleStrategy() and then occasionally call IdleStrategy.idle() or IdleStrategy.idle(int), especially when polling the Image returns 0.

Parameters:

cluster - with which the service can interact.

snapshotImage - from which the service can load its archived state which can be null when no snapshot.

onSessionOpen

void onSessionOpen(ClientSession session,
                   long timestamp)

A session has been opened for a client to the cluster.

Parameters:

session - for the client which have been opened.

timestamp - at which the session was opened.

onSessionClose

void onSessionClose(ClientSession session,
                    long timestamp,
                    CloseReason closeReason)

A session has been closed for a client to the cluster.

Parameters:

session - that has been closed.

timestamp - at which the session was closed.

closeReason - the session was closed.

onSessionMessage

void onSessionMessage(ClientSession session,
                      long timestamp,
                      DirectBuffer buffer,
                      int offset,
                      int length,
                      Header header)

A message has been received to be processed by a clustered service.

Parameters:

session - for the client which sent the message. This can be null if the client was a service.

timestamp - for when the message was received.

buffer - containing the message.

offset - in the buffer at which the message is encoded.

length - of the encoded message.

header - aeron header for the incoming message.

onTimerEvent

void onTimerEvent(long correlationId,
                  long timestamp)

A scheduled timer has expired.

Parameters:

correlationId - for the expired timer.

timestamp - at which the timer expired.

onTakeSnapshot

void onTakeSnapshot(ExclusivePublication snapshotPublication)

The service should take a snapshot and store its state to the provided archive Publication.

Note: As this is a potentially long running operation the implementation should use Cluster.idleStrategy() and then occasionally call IdleStrategy.idle() or IdleStrategy.idle(int), especially when the snapshot ExclusivePublication returns Publication.BACK_PRESSURED.

Parameters:

snapshotPublication - to which the state should be recorded.

onRoleChange

void onRoleChange(Cluster.Role newRole)

Notify that the cluster node has changed role.

Parameters:

newRole - that the node has assumed.

onTerminate

void onTerminate(Cluster cluster)

Called when the container is going to terminate.

Parameters:

cluster - with which the service can interact.

onNewLeadershipTermEvent

default void onNewLeadershipTermEvent(long leadershipTermId,
                                      long logPosition,
                                      long timestamp,
                                      long termBaseLogPosition,
                                      int leaderMemberId,
                                      int logSessionId,
                                      TimeUnit timeUnit,
                                      int appVersion)

An election has been successful and a leader has entered a new term.

Parameters:

leadershipTermId - identity for the new leadership term.

logPosition - position the log has reached as the result of this message.

timestamp - for the new leadership term.

termBaseLogPosition - position at the beginning of the leadership term.

leaderMemberId - who won the election.

logSessionId - session id for the publication of the log.

timeUnit - for the timestamps in the coming leadership term.

appVersion - for the application configured in the consensus module.