com.twitter.common.util
Class StateMachine<T>

java.lang.Object
  extended by com.twitter.common.util.StateMachine<T>
Type Parameters:
T - THe type of objects that the caller uses to represent states. TODO(William Farner): Consider merging the stats-tracking ala PipelineStats into this.

public class StateMachine<T>
extends Object

Represents a state machine that is not necessarily a Finite State Machine. The caller may configure the state machine to permit only known state transitions, or to only disallow known state transitions (and permit unknown transitions).


Nested Class Summary
static class StateMachine.Builder<T>
          Builder to create a state machine.
static class StateMachine.IllegalStateTransitionException
           
static class StateMachine.Rule<T>
          A state and its allowed transitions (if any) and (optional) callback.
static class StateMachine.Transition<T>
          Representation of a state transition.
 
Method Summary
static
<T> StateMachine.Builder<T>
builder(String name)
          Convenience method to create a builder object.
 void checkState(Set<T> allowedStates)
          Checks that the current state is one of the allowedStates and throws if it is not.
 void checkState(T expectedState)
          Checks that the current state is the expectedState and throws if it is not.
<O,E extends Exception>
O
doInState(T expectedState, ExceptionalSupplier<O,E> work)
          Executes the supplied work if the state machine is in the expectedState, postponing any concurrently requested transition(Object) until after the execution of the work.
 String getName()
          Gets the name of this state machine.
 T getState()
          Fetches the state that the machine is currently in.
 boolean transition(T nextState)
          Transitions the machine into state nextState.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getName

public String getName()
Gets the name of this state machine.

Returns:
The state machine name.

getState

public T getState()
Fetches the state that the machine is currently in.

Returns:
Current state.

checkState

public void checkState(T expectedState)
Checks that the current state is the expectedState and throws if it is not.

Parameters:
expectedState - The expected state
Throws:
IllegalStateException - if the current state is not the expectedState.

checkState

public void checkState(Set<T> allowedStates)
Checks that the current state is one of the allowedStates and throws if it is not.

Parameters:
allowedStates - The allowed states.
Throws:
IllegalStateException - if the current state is not the expectedState.

doInState

public <O,E extends Exception> O doInState(T expectedState,
                                           ExceptionalSupplier<O,E> work)
            throws E extends Exception
Executes the supplied work if the state machine is in the expectedState, postponing any concurrently requested transition(Object) until after the execution of the work.

Type Parameters:
O - The type returned by the unit of work.
E - The type of exception that may be thrown by the unit of work.
Parameters:
expectedState - The expected state the work should be performed in.
work - The work to perform in the expectedState.
Returns:
The result of the unit of work if the current state is the expectedState.
Throws:
IllegalStateException - if the current state is not the expectedState.
E - if the unit of work throws.
E extends Exception

transition

public boolean transition(T nextState)
                   throws StateMachine.IllegalStateTransitionException
Transitions the machine into state nextState.

Parameters:
nextState - The state to move into.
Returns:
true if the transition was allowed, false otherwise.
Throws:
StateMachine.IllegalStateTransitionException - If the state transition is not allowed.

builder

public static <T> StateMachine.Builder<T> builder(String name)
Convenience method to create a builder object.

Type Parameters:
T - Type of builder to create.
Parameters:
name - Name of the state machine to create a builder for.
Returns:
New builder.