org.jgroups.blocks

## Class GroupRequest

- java.lang.Object
- - org.jgroups.blocks.Request
  - - org.jgroups.blocks.GroupRequest

- All Implemented Interfaces:
    java.util.concurrent.Future, RspCollector, Command, NotifyingFuture

      public class GroupRequest
      extends Request

  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.

  Author:
    Bela Ban

- - ### Field Summary

    - ### Fields inherited from class org.jgroups.blocks.Request

      `block_for_results, completed, corr, done, GET_ABS_MAJORITY, GET_ALL, GET_FIRST, GET_MAJORITY, GET_N, GET_NONE, listener, lock, log, options, req_id, REQUEST_ID, request_msg, transport`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GroupRequest(Message m, RequestCorrelator corr, Address target, RequestOptions options)`
    `GroupRequest(Message msg, RequestCorrelator corr, java.util.Collection<Address> targets, RequestOptions options)`
    `GroupRequest(Message m, Transport transport, java.util.Collection<Address> mbrs, RequestOptions options)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `RspList` | `get()`
    `RspList` | `get(long timeout, java.util.concurrent.TimeUnit unit)`
    `boolean` | `getAnycasting()`
    `RspList` | `getResults()` Returns the results as a RspList
    `void` | `receiveResponse(java.lang.Object response_value, Address sender)` Callback (called by RequestCorrelator or Transport).
    `protected boolean` | `responsesComplete()`
    `void` | `sendRequest()`
    `void` | `setAnycasting(boolean anycasting)`
    `void` | `suspect(Address suspected_member)` Callback (called by RequestCorrelator or Transport).
    `java.lang.String` | `toString()`
    `void` | `viewChange(View new_view)` Any member of 'membership' that is not in the new view is flagged as SUSPECTED.

    - ### Methods inherited from class org.jgroups.blocks.Request

      `cancel, checkCompletion, execute, getBlockForResults, getRequestId, getResponsesComplete, isCancelled, isDone, modeToString, responsesComplete, setBlockForResults, setListener, setResponseFilter, waitForResults`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### GroupRequest

          public GroupRequest(Message msg,
                      RequestCorrelator corr,
                      java.util.Collection<Address> targets,
                      RequestOptions options)

      Parameters:
        `msg` - 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
        `targets` - The targets, which are supposed to receive the message. Any receiver not in this set will discard the message. Targets are always a subset of the current membership
        `options` - The request options to be used for this call

    - #### GroupRequest

          public GroupRequest(Message m,
                      RequestCorrelator corr,
                      Address target,
                      RequestOptions options)

    - #### GroupRequest

          public GroupRequest(Message m,
                      Transport transport,
                      java.util.Collection<Address> mbrs,
                      RequestOptions options)

  - ### Method Detail

    - #### getAnycasting

          public boolean getAnycasting()

    - #### setAnycasting

          public void setAnycasting(boolean anycasting)

    - #### sendRequest

          public void sendRequest()
                           throws java.lang.Exception

      Specified by:
        `sendRequest` in class `Request`
      Throws:
        `java.lang.Exception`

    - #### receiveResponse

          public void receiveResponse(java.lang.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`
      Specified by:
        `receiveResponse` in class `Request`

    - #### 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`
      Specified by:
        `suspect` in class `Request`

    - #### 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`
      Specified by:
        `viewChange` in class `Request`

    - #### getResults

          public RspList getResults()

      Returns the results as a RspList

    - #### get

          public RspList get()
                      throws java.lang.InterruptedException,
                             java.util.concurrent.ExecutionException

      Throws:
        `java.lang.InterruptedException`
        `java.util.concurrent.ExecutionException`

    - #### get

          public RspList get(long timeout,
                    java.util.concurrent.TimeUnit unit)
                      throws java.lang.InterruptedException,
                             java.util.concurrent.ExecutionException,
                             java.util.concurrent.TimeoutException

      Throws:
        `java.lang.InterruptedException`
        `java.util.concurrent.ExecutionException`
        `java.util.concurrent.TimeoutException`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `Request`

    - #### responsesComplete

          protected boolean responsesComplete()

      Specified by:
        `responsesComplete` in class `Request`

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.