org.jgroups.blocks

Class GroupRequest

public class GroupRequest extends Object implements RspCollector, Command

Sends a message to all members of the group and waits for all responses (or timeout). Returns a boolean value (success or failure). Results (if any) can be retrieved when done.

The supported transport to send requests is currently either a RequestCorrelator or a generic Transport. One of them has to be given in the constructor. It will then be used to send a request. When a message is received by either one, the receiveResponse() of this class has to be called (this class does not actively receive requests/responses itself). Also, when a view change or suspicion is received, the methods viewChange() or suspect() of this class have to be called.

When started, an array of responses, correlating to the membership, is created. Each response is added to the corresponding field in the array. When all fields have been set, the algorithm terminates. This algorithm can optionally use a suspicion service (failure detector) to detect (and exclude from the membership) fauly members. If no suspicion service is available, timeouts can be used instead (see execute()). When done, a list of suspected members can be retrieved.

Because a channel might deliver requests, and responses to different requests, the GroupRequest class cannot itself receive and process requests/responses from the channel. A mechanism outside this class has to do this; it has to determine what the responses are for the message sent by the execute() method and call receiveResponse() to do so.

Requirements: lossless delivery, e.g. acknowledgment-based message confirmation.

Version: $Revision: 1.16 $

Author: Bela Ban

Field Summary
protected RequestCorrelatorcorr
protected booleandone
protected intexpected_mbrs
static intGET_ABS_MAJORITY
return majority (of all members, may block)
static intGET_ALL
return all responses
static intGET_FIRST
return only first response
static intGET_MAJORITY
return majority (of all non-faulty members)
static intGET_N
return n responses (may block)
static intGET_NONE
return no response (async call)
protected Messagerequest_msg
protected intrsp_mode
protected longtimeout
protected Transporttransport
Constructor Summary
GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode)
GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode, long timeout, int expected_mbrs)
GroupRequest(Message m, Transport transport, Vector members, int rsp_mode)
GroupRequest(Message m, Transport transport, Vector members, int rsp_mode, long timeout, int expected_mbrs)
Method Summary
booleanexecute()
Sends the message.
AddressgetCaller()
intgetNumSuspects()
RspListgetResults()
Returns the results as a RspList
VectorgetSuspects()
booleanisDone()
voidreceiveResponse(Message m)
Callback (called by RequestCorrelator or Transport).
voidreset(Vector mbrs)
This method sets the membership variable to the value of members.
voidsetCaller(Address caller)
voidsuspect(Address suspected_member)
Callback (called by RequestCorrelator or Transport).
StringtoString()
voidviewChange(View new_view)
Any member of 'membership' that is not in the new view is flagged as SUSPECTED.

Field Detail

corr

protected RequestCorrelator corr

done

protected boolean done

expected_mbrs

protected int expected_mbrs

GET_ABS_MAJORITY

public static final int GET_ABS_MAJORITY
return majority (of all members, may block)

GET_ALL

public static final int GET_ALL
return all responses

GET_FIRST

public static final int GET_FIRST
return only first response

GET_MAJORITY

public static final int GET_MAJORITY
return majority (of all non-faulty members)

GET_N

public static final int GET_N
return n responses (may block)

GET_NONE

public static final int GET_NONE
return no response (async call)

request_msg

protected Message request_msg

rsp_mode

protected int rsp_mode

timeout

protected long timeout

transport

protected Transport transport

Constructor Detail

GroupRequest

public GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode)

Parameters: m The message to be sent corr The request correlator to be used. A request correlator sends requests tagged with a unique ID and notifies the sender when matching responses are received. The reason GroupRequest uses it instead of a Transport is that multiple requests/responses might be sent/received concurrently. members The initial membership. This value reflects the membership to which the request is sent (and from which potential responses are expected). Is reset by reset(). rsp_mode How many responses are expected. Can be

  1. GET_ALL: wait for all responses from non-suspected members. A suspicion service might warn us when a member from which a response is outstanding has crashed, so it can be excluded from the responses. If no suspision service is available, a timeout can be used (a value of 0 means wait forever). If a timeout of 0 is used, no suspicion service is available and a member from which we expect a response has crashed, this methods blocks forever !.
  2. GET_FIRST: wait for the first available response.
  3. GET_MAJORITY: wait for the majority of all responses. The majority is re-computed when a member is suspected.
  4. GET_ABS_MAJORITY: wait for the majority of all members. This includes failed members, so it may block if no timeout is specified.
  5. GET_N: wait for N members. Return if n is >= membership+suspects.
  6. GET_NONE: don't wait for any response. Essentially send an asynchronous message to the group members.

GroupRequest

public GroupRequest(Message m, RequestCorrelator corr, Vector members, int rsp_mode, long timeout, int expected_mbrs)

Parameters: timeout Time to wait for responses (ms). A value of <= 0 means wait indefinitely (e.g. if a suspicion service is available; timeouts are not needed).

GroupRequest

public GroupRequest(Message m, Transport transport, Vector members, int rsp_mode)

GroupRequest

public GroupRequest(Message m, Transport transport, Vector members, int rsp_mode, long timeout, int expected_mbrs)

Parameters: timeout Time to wait for responses (ms). A value of <= 0 means wait indefinitely (e.g. if a suspicion service is available; timeouts are not needed).

Method Detail

execute

public boolean execute()
Sends the message. Returns when n responses have been received, or a timeout has occurred. n can be the first response, all responses, or a majority of the responses.

getCaller

public Address getCaller()

getNumSuspects

public int getNumSuspects()

getResults

public RspList getResults()
Returns the results as a RspList

getSuspects

public Vector getSuspects()

isDone

public boolean isDone()

receiveResponse

public void receiveResponse(Message m)
Callback (called by RequestCorrelator or Transport). Adds a response to the response table. When all responses have been received, execute() returns.

reset

public void reset(Vector mbrs)
This method sets the membership variable to the value of members. It requires that the caller already hold the rsp_mutex lock.

Parameters: mbrs The new list of members

setCaller

public void setCaller(Address caller)

suspect

public void suspect(Address suspected_member)
Callback (called by RequestCorrelator or Transport). Report to GroupRequest that a member is reported as faulty (suspected). This method would probably be called when getting a suspect message from a failure detector (where available). It is used to exclude faulty members from the response list.

toString

public String toString()

viewChange

public void viewChange(View new_view)
Any member of 'membership' that is not in the new view is flagged as SUSPECTED. Any member in the new view that is not in the membership (ie, the set of responses expected for the current RPC) will not be added to it. If we did this we might run into the following problem:
Copyright ? 1998-2005 Bela Ban. All Rights Reserved.