Although RequestCorrelator can be used by itself, GroupRequest (JavaGroups.Algorithms.GroupRequest) is a building block making use of request correlator, that simplifies sending messages to all members of a group and collecting responses. Its most important public methods are:
public class GroupRequest { public GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode); public GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode, long timeout, int expected_mbrs); public synchronized boolean Execute(); public void Reset(Vector members); public RspList GetResults(); public Vector GetSuspects(); }
The 2 constructors need a request correlator, the message to be sent, a response mode, an initial membership, a timeout and the number of expected members. The initial membership is a vector of member addresses from which responses are expected. If the message's destination is not null, meaning that the message is to be sent to a single destination (unicast), then the membership might only contain a single address, namely that of the destination from which a response is expected. If no response is expected, the membership vector can be empty.
The timeout can be used in combination with, or as replacement for, a suspicion service. If a message is sent to members P, Q and R, and responses are expected from all members, then, if R crashes, a suspicion service will feed this information to the underlying request correlator, which in turn will feed it to the group request object sitting on top of the correlator. A group request that has already received responses from P and Q will block until it receives the response from R, or until a suspicion message about R is received. If no suspicion service is available, a timeout specifies the maximum amount of time a group request should wait for all responses, preventing blocking. Timeouts and a suspicion service can also be combined. A timeout smaller than or equal to 0 means wait indefinitely.
The number of expected members is the number of responses expected. It is only used if the response mode is GET_N (see below).
The response mode is one of
Method Execute returns true if the group request succeeded, and false in case of an error. Reset allows to reuse the same group request object, by just adjusting the membership, and resending the same message (note that there are other reset methods). GetSuspects returns a vector of suspected members (empty if none were suspected), and GetResults returns a response list RspList (JavaGroups.RspList) which can be queried for the response from each member, whether a member did not send a response, whether it crashed, and - if a response was received - its value.
Note that the group request relies on a loss-less message delivery: no response may ever be lost unless the sender crashed. This property must be guaranteed by the underlying transport, by for example adding a retransmission layer to the protocol stack. If this is not the case, a group request may block forever, e.g. if a response was generated by a receiver, but was lost, and the receiver did not crash (unless a timeout was specified).