com.sonicsw.mf.common.runtime
Interface IStateManager

public interface IStateManager

A concrete implementation of the IStateManager interface acts as a central point for managing the state of an entity, such as the fault tolerant state of the DS or AM.

A concrete state manager implementation is configured with a set.

State controllers (implementers of IStateController) may be registered to effect the behavioral adjustments associated with a particular state transition.

State listeners (implementors of IStateListener) may be added to be informed when a state transitions starts and whether the transition succeeds or fails.

A developer should not attempt to request a state change from either a state controller or a state listener.

Method Summary

short	getState(java.lang.Object obj) Get the state of the specified object.
void	registerStateController(IStateController stateController, short fromState, short toState, java.lang.Object obj) Register a state controller that will cause the behvioral changes associated with the transition from one specified state to another specified state.
void	registerStateListener(IStateListener stateListener, java.lang.Object obj) Register a listener for the changes in state of the state-managed object.
boolean	requestStateChange(short expectedCurrentState, short desiredState, java.lang.Object obj) The thread that detects the condition that requires a state change will call this method to effect the state change.

Method Detail

getState

short getState(java.lang.Object obj)

Get the state of the specified object. For a concrete implementation that is designed to managed only a single object's state, the input argument could be null. For a concrete implementation that is designed to manage the states of multiple objects, the input argument would be the reference to the object instance whose state is to be returned.

Parameters:

Object - The object instance whose current state is to be returned.

Returns:

short The current state of the object instance.

registerStateController

void registerStateController(IStateController stateController,
                             short fromState,
                             short toState,
                             java.lang.Object obj)

Register a state controller that will cause the behvioral changes associated with the transition from one specified state to another specified state.

Parameters:

stateController - The concrete implementation of IStateController that will perform the steps necessary for the state transition

fromState - The state at which the state-managed entity must be in order for the controller will be invoked

toState - The state to which the state-managed entity must transition in order for the controller to be invoked

obj - The state-managed object with which the controller is associated

registerStateListener

void registerStateListener(IStateListener stateListener,
                           java.lang.Object obj)

Register a listener for the changes in state of the state-managed object.

Parameters:

stateListener - The concrete implementation of IStateListener

obj - The state-managed object to which the listener will be associated

requestStateChange

boolean requestStateChange(short expectedCurrentState,
                           short desiredState,
                           java.lang.Object obj)
                           throws NonRecoverableStateChangeException,
                                  RecoverableStateChangeException

The thread that detects the condition that requires a state change will call this method to effect the state change.

The calling thread is expected to have previously obtained the current state and to have made the decision as to what is the next state that should be applied. To ensure synchronization between calls, the caller is required to provide the expected current state so that it can possibly retry if another thread changed the state between the callers calls. If the current state, from the state manager's perspective, does not match the current state expected by the caller, then a value of "false" should be returned. Likewise, if the transition to the requested desired state from the current state does not represent an allowable transition, then a value of "false" should be returned.

Parameters:

expectedCurrentState - The current state obtained immediately before calling this method

desiredState - The state the caller wishes to transition to

obj - The state-managed object whose state is to be changed

Returns:

Return true if the state transition was successful, false if not.

Throws:

NonRecoverableStateChangeException

RecoverableStateChangeException