Getting the group's state

A newly joined member may wish to retrieve the state of the group before starting work. This is done calling either GetState of GetStates. The first method returns the state of one member (in most cases, of the oldest member, the coordinator) whereas the latter returns the states of all members. This method returns true or false, depending on whether a valid state could be retrieved. For example, if a member is a singleton, then calling this method would always return false^3.3.

The actual state is returned as the return value of one of the subsequent Receive calls, in the form of a SetStateEvent object. If GetState(s) returned true, then a valid state (non-null) will be returned, otherwise a null state will be returned.

Note that state transfer is currently only available with JChannel !

The following code fragment shows how a group member participates in state transfers:

        channel=new JChannel("UDP:PING:FD:GMS:STATE_TRANSFER:QUEUE");
        channel.SetOpt(Channel.GET_STATE_EVENTS, new Boolean(true));
        channel.Connect("TestChannel");
        boolean rc=channel.GetState(5000);

        ...

        Object ret=channel.Receive(0);
        if(ret instanceof Message)
            ;
        else if(ret instanceof GetStateEvent) {
            // copy=CopyState(state)
            channel.ReturnState(copy);
        }
        else if(ret instanceof SetStateEvent) {
            SetStateEvent e=(SetStateEvent)ret;
            // set state from ret.GetArg();
        }

A JChannel has to be created whose stack includes the STATE_TRANSFER protocol. Option GET_STATE_EVENTS should be enabled, as the channel might probably want to return its current state if asked. Method GetState() subsequently asks the channel to return the current state. If there is a current state (there may not be any other members in the group !), then true is returned. In this case, one of the subsequent Receive method invocations on the channel will return a SetStateEvent object which contains the current state. In this case, the caller sets its state to the one received from the channel.

If state transfer events are enabled, then Receive might return a GetStateEvent object, requesting the state of the member to be returned. In this case, a copy of the current state should be made and returned using JChannel.ReturnState. It is important to a) synchronize access to the state when returning it since other accesses may modify it while it is being returned and b) make a copy of the state since other accesses after returning the state may still be able to modify it ! This is possible because the state is not immediately returned, but travels down the stack (in the same address space), and a reference to it could still alter it.

The details of state transfer as implemented in JavaGroups are discussed in section 7.2.11.