Shoal Messaging
To better understand this document, please read Shoal Design Document
Shoal's GroupManagementService provides its clients a GroupHandle for sending messages to individual members, and to the entire group. In fact, components in a process can send messages to their respective counterpart components in the other group member processes.
Sending Messages
For sending messages in a scalable, and reliable manner, with delivery guarantees, GMS relies on the underlying Group Communication Provider to provide appropriate protocols for the same. GMS has identified Jxta and JGroups open source packages as possible candidates with the requisite design center, and core performance to that provide such reliability and performance guarantees. Both JXTA and JGroups support messaging using UDP/Multicast and TCP transports.
In order to send messages to the group or an individual target member, GMS clients use the GroupHandle object. The API specification is as follows:
/**
* Sends a message to all members of the Group. Expects a target component name and a byte array as parameter
* carrying the payload. Specifying a null component name would result in the message being delivered to all registered
* components in the target member instance.
* @param targetComponentName
* @param message
*/
void sendMessage(String targetComponentName, byte[] message);
/**
* Sends a message to a single member of the group. Expects a targetServerToken representing the recipient
* member's id, the target component name in the target recipient member, and a byte array as parameter carrying
* the payload. Specifying a null component name would result in the message being delivered to all registered
* components in the target member instance.
* @param targetServerToken
* @param targetComponentName
* @param message
*/
void sendMessage(String targetServerToken, String targetComponentName, byte[] message);
Receiving Messages
In order to setup a component (GMS client) to receive a message sent by another group member's component, the recipient component should register its MessageActionFactory implementation with GMS by calling as follows :
GroupManagementService gms = GMSFactory.getGMSModule(groupName);
gms.addActionFactory(MessageActionFactory);
This is similar to the failure notification construct, in that, GMS clients implement two interfaces, namely, MessageActionFactory and MessageAction in order to receive messages. When a message is received by GMS, it analyzes the message to determine the component to which the message was addressed to, and then invokes the appropriate instance of MessageActionFactory implementation to call its produceAction() method passing in a MessageSignal instance.
