Shoal Group Event Notifications

To better understand this document, read : Shoal Design Document

Shoal's GroupManagementService (GMS) provides a client API that allows consuming client components within a process to receive callbacks when group events occur. The Group Events available from GMS are broadly of following types :

• A Member Joining the group
• A Member advertising to the group that it is Joined And Ready to process operations
• Suspect or in-doubt state of a member 
• Failure of a member
• Selection of a member for initiating Recovery operations
• Administratively Planned Shutdown
• Group Leader change notification
  

These events are notified to consuming applications through client API, part of which is implemented by clients and part provided by GMS. Group Events are notified and handled through an Actuator-Sensor pattern (Reference: Shoal Design Document ). Each event is sensed by GMS and an object of Signal type is raised for notifying the client. The client registers interest in the group event by registering an implementation of an ActionFactory interface with a reference to an implementation of an Action interface. ActionFactory produces an Action and an Action consumes a Signal. Each group event is typified by a specific triplet of interface types. For instance, for the Failure event, the triplet interfaces of interest would be :

• FailureNotificationActionFactory (implemented by the client),

• FailureNotificationAction (implemented by client), and

• FailureNotificationSignal (implemented by GMS).

The following table summarizes the Event and corresponding client API to implement for the purpose of consuming the event, and how to register the same with GMS:

Group Event	Client Implements	GMS implements	Client Registers through
Failure	FailureNotificationActionFactory FailureNotificationAction	FailureNotificationSignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(FailureNotificationActionFactory);
Indoubt/Suspect	FailureSuspectedActionFactory FailureSuspectedAction	FailureSuspectedSignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(FailureSuspectedActionFactory)
Recovery(reference Shoal Automated Delegated Recovery Initiation)	FailureRecoveryActionFactory FailureRecoveryAction	FailureRecoverySignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(FailureRecoveryActionFactory)
Planned Shutdown	PlannedShutdownActionFactory PlannedShutdownAction	PlannedShutdownSignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(PlannedShutdownActionFactory)
GroupLeadershipNotification	GroupLeadershipActionFactory GroupLeadershipAction	GroupLeadershipSignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(GroupLeadershipActionFactory)
Join Notification	JoinNotificationActionFactory JoinNotificationAction	JoinNotificationSignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(JoinNotificationActionFactory)
Joined and Ready Notification	JoinedAndReadyNotificationActionFactory JoinedAndReadyNotificationAction	JoinedAndReadySignal	GroupManagementService gms = GMSFactory.getGMSModule(String groupName); gms.addFactory(JoinedAndReadyActionFactory)

Convenience Interface

As a convenience to GMS clients, default implementations of the above ActionFactory and Action interface types have been provided as part of the shoal libraries under the com.sun.enterprise.ee.cms.impl.client package.  

To take advantage of these implementations of these client interfaces, you will need to implement an interface CallBack#processNotification(Signal) to access the Signal's APIs.  This avoids the need to implement the above-mentioned ActionFactory and Action interfaces.