The architecture of JavaGroups.JavaStack.MessageProtocol is shown in fig. 4.3.
Methods Up and Down are inherited from Protocol, but they are made final, i.e. they cannot be overridden in further subclasses of MessageProtocol. To handle events, methods HandleDownEvent and HandleUpEvent are introduced: Up will call HandleUpEvent and, if the return value is true, pass the message up the stack, or discard it. The same applies to Down: if HandleDownEvent return false, the message is discarded, otherwise it is passed down to the next layer.
Methods SendMessage and CastMessage provide synchronous group messages (discussed below): they make use of GroupRequests and a RequestCorrelator (see 3.4.4 and 3.4.3) to do so. Any time one of the two methods is called, a new group request will be created and registered with the request correlator. The group request object then uses RequestCorrelator.SendRequest to send a message. The request correlator will assign a unique request number to the request, add a header to is so that it will be received by the correct peer layer in the receiver's protocol stack, and passes it down the stack.
The peer layer in the receiver's stack receives the message, and calls HandleUpEvent to do any local processing based on the message. If false is returned, the message is discarded. Else method Receive of the request correlator is called. It checks the header to see whether the message was generated by the corresponding peer layer in the sender's stack and, if so, receives it. Otherwise it rejects it by returning false. In this case, the message is just passed on to the layer above the current one. Otherwise, the header is scrutinized to check whether the message is a response or request. If it is a response, the corresponding request is looked up and the message is delivered (calling method RspCollector.ReceiveResponse). Otherwise, method Handle (which is overridden by a subclass) is called. It processes the request and returns an object. If the request was not one-way, i.e. requires a response, the object is serialized and send back in a response message.
The important methods to implement a peer protocol are CastMessage, SendMessage and Handle:
public RspList CastMessage(Vector dests, Message msg, int mode, long timeout);
public Object SendMessage(Message msg, int mode, long timeout)
throws Timeout, Suspected;
public Object Handle(Message req);
CastMessage sends message msg to all members of dests and waits for mode responses or a timeout (whichever comes first) and returns a response list (cf. 3.4.4). Mode can be any of the following:
When waiting for any responses, and a group member has been suspected, then that response is marked as suspected in the response list, without causing the caller to block indefinitely. Alternatively, a timeout can be employed: when mode responses are expected and not all have been received yet, when the timeout occurs, the call returns and the resulting response list contains all the responses received so far. A timeout of 0 means to wait indefinitely.
SendMessage is similar to CastMessage except that the message is sent only to a single group member. Argument mode should be either NONE or FIRST (although ALL and MAJORITY would also work). Instead of returning a response list, an object is returned, representing the response from a single receiver (may also be null). If the receiver is suspected, or a timeout has occurred, then the corresponding exception is thrown.
Callback Handle will probably be overridden by a peer protocol that processes incoming requests. It accepts the request in the form of a message. The body of the message will contain the request data, e.g. a request object. Depending on the request, Handle will perform some processing and optionally return a result value (or null). If the request was not one-way, a response message will be generated (with the result in the message's buffer) and sent back to the sender of the request.