Package org.jgroups.blocks

Class GroupRequest

  • All Implemented Interfaces:
    RspCollector, Command
    public class GroupRequest
extends java.lang.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 Detail

      • GET_FIRST

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

      • GET_MAJORITY

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

      • GET_ABS_MAJORITY

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

      • GET_NONE

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

      • request_msg

        protected final Message request_msg

      • rsp_mode

        protected int rsp_mode

      • done

        protected boolean done

      • timeout

        protected long timeout

      • expected_mbrs

        protected int expected_mbrs

    • Constructor Detail

      • GroupRequest

        public GroupRequest​(Message m,
                    RequestCorrelator corr,
                    java.util.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,
                    java.util.Vector<Address> 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,
                    java.util.Vector<Address> members,
                    int rsp_mode)

      • GroupRequest

        public GroupRequest​(Message m,
                    Transport transport,
                    java.util.Vector<Address> 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

      • getCaller

        public Address getCaller()

      • setCaller

        public void setCaller​(Address caller)

      • setResponseFilter

        public void setResponseFilter​(RspFilter filter)

      • execute

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

      • execute

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

      • reset

        public final void reset​(java.util.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​(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

      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getNumSuspects

        public int getNumSuspects()

      • getSuspects

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

      • isDone

        public boolean isDone()