Class GroupRequest

java.lang.Object
org.jgroups.blocks.GroupRequest
All Implemented Interfaces:
RspCollector, Command
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:
$Id: GroupRequest.java,v 1.30.2.3 2008/11/17 13:37:59 belaban Exp $
Author:
Bela Ban

  • Field Details

    • GET_FIRST

      public static final int GET_FIRST
      return only first response
      See Also:

    • GET_ALL

      public static final int GET_ALL
      return all responses
      See Also:

    • GET_MAJORITY

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

    • GET_ABS_MAJORITY

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

    • GET_N

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

    • GET_NONE

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

    • request_msg

      protected final Message request_msg

    • corr

      protected final RequestCorrelator corr

    • transport

      protected Transport transport

    • rsp_filter

      protected RspFilter rsp_filter

    • rsp_mode

      protected int rsp_mode

    • done

      protected boolean done

    • timeout

      protected long timeout

    • expected_mbrs

      protected int expected_mbrs

  • Constructor Details

    • GroupRequest

      public GroupRequest(Message m, RequestCorrelator corr, Vector<Address> 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<Address> members, int rsp_mode, long timeout, int expected_mbrs)
      Parameters:
      timeout - Time to wait for responses (ms). A value of invalid input: '<'= 0 means wait indefinitely (e.g. if a suspicion service is available; timeouts are not needed).

    • GroupRequest

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

    • GroupRequest

      public GroupRequest(Message m, Transport transport, Vector<Address> members, int rsp_mode, long timeout, int expected_mbrs)
      Parameters:
      timeout - Time to wait for responses (ms). A value of invalid input: '<'= 0 means wait indefinitely (e.g. if a suspicion service is available; timeouts are not needed).

  • Method Details

    • getCaller

      public Address getCaller()

    • setCaller

      public void setCaller(Address caller)

    • setResponseFilter

      public void setResponseFilter(RspFilter filter)

    • execute

      public boolean execute() throws Exception
      Specified by:
      execute in interface Command
      Throws:
      Exception

    • execute

      public boolean execute(boolean use_anycasting) throws Exception
      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.
      Throws:
      Exception

    • reset

      public final void reset(Vector<Address> 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

    • receiveResponse

      public void receiveResponse(Object response_value, Address sender)
      Callback (called by RequestCorrelator or Transport). Adds a response to the response table. When all responses have been received, execute() returns.
      Specified by:
      receiveResponse in interface RspCollector

    • 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.
      Specified by:
      suspect in interface RspCollector

    • 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:
      • Membership is {A,B}
      • A sends a synchronous group RPC (which sleeps for 60 secs in the invocation handler)
      • C joins while A waits for responses from A and B
      • If this would generate a new view {A,B,C} and if this expanded the response set to {A,B,C}, A would wait forever on C's response because C never received the request in the first place, therefore won't send a response.
      Specified by:
      viewChange in interface RspCollector

    • getResults

      public RspList getResults()
      Returns the results as a RspList

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getNumSuspects

      public int getNumSuspects()

    • getSuspects

      public Vector<Address> getSuspects()
      Returns the list of suspected members. An attempt to modify the return value will throw an excxeption

    • isDone

      public boolean isDone()