GroupRequest

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.

Note that a group request with multiple destinations is always sent to the whole membership (using multicasting) since there is no way of specifying subgroups using IP multicast. However, the members parameter to a group request determines the members from which we expect replies. If a request should not be received by all members (a true subgroup), then multiple unicasts should be sent.

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

GroupRequest.GET_FIRST

Execute returns as soon as the first response has been received (or a timeout has elapsed, or a suspicion message was received).

GroupRequest.GET_ALL

Execute returns when responses from all members have been received (or a timeout has occurred, or a suspicion message was received).

GroupRequest.GET_MAJORITY

Execute returns when the majority of the members have responded (or a timeout occurred, or a suspicion message was received). The majority is computed using the membership given in the constructor. If a suspicion message is received, the majority is computed anew (dynamically), without the suspected member.

GroupRequest.GET_ABS_MAJORITY

Execute returns when the majority of the members have responded. Contrary to the above mode, the majority is not re-computed when a member crashes.

GroupRequest.GET_N

Execute returns when n responses have been received. If n is greater than the number of members in the membership, then the call will block forever (unless a timeout is specified).

GroupRequest.GET_NONE

Execute returns immediately. The message is sent asynchronously, no responses are expected, and none will be generated at the receivers' end.

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).