org.apache.gobblin.fsm

Class FiniteStateMachine<T>

java.lang.Object

org.apache.gobblin.fsm.FiniteStateMachine<T>

Type Parameters:

T -

public class FiniteStateMachine<T>
extends Object

An implementation of a basic FiniteStateMachine that allows keeping track of the state its state and gating certain logic on whether a transition is valid or not. This class is useful in situations where logic is complex, possibly multi-threaded, and can take multiple paths. Certain pieces of logic (for example running a job, publishing a dataset, etc) can only happen if other actions ended correctly, and the FSM is a way of simplifying the encoding and verification of those conditions. It is understood that state transitions may not be instantaneous, and that other state transitions should not start until the current one has been resolved. All public methods of this class will wait until the FSM is in a non-transitioning state. If multiple transitions are queued at the same time, the order in which they are executed is essentially random. The states supported by FSM can be enums or instances of any base type. The legality of a transition is determined by equality, i.e. if a transition A -> B is legal, the current state is A' and the desired end state is B', the transition will be legal if A.equals(A') && B.equals(B'). This allows for storing additional information into the current state as long as it does not affect the equality check (i.e. fields that are not compared in the equals check can store state metadata, etc.). Suggested Usage: FiniteStateMachine fsm = new FiniteStateMachine.Builder().addTransition(START_SYMBOL, END_SYMBOL).build(initialSymbol); try (Transition transition = fsm.startTransition(MY_END_STATE)) { try { // my logic } catch (MyException exc) { transition.changeEndState(MY_ERROR); } } catch (UnallowedTransitionException exc) { // Cannot execute logic because it's an illegal transition! } catch (ReentrantStableStateWait exc) { // Somewhere in the logic an instruction tried to do an operation with the fsm that would likely cause a deadlock } catch (AbandonedTransitionException exc) { // Another thread initiated a transition and became inactive ending the transition } catch (InterruptedException exc) { // Could not start transition because thread got interrupted while waiting for a non-transitioning state } catch (FailedTransitionCallbackException exc) { // A callback in the transition start or end states has failed. exc.getTransition().changeEndState(MY_ERROR).closeWithoutCallbacks(); // example handling }

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FiniteStateMachine.AbandonedTransitionException Thrown when a transition was initiated by a thread that no longer exists, likely implying that the transition can never be closed.
static class	FiniteStateMachine.Builder<T> Used to build a FiniteStateMachine instance.
static class	FiniteStateMachine.FailedCallback
static class	FiniteStateMachine.FailedTransitionCallbackException Thrown when the callbacks when closing a transition fail.
static class	FiniteStateMachine.ReentrantStableStateWait Thrown when a thread that has started a transition is waiting for a non-transitioning state, which is a deadlock situation.
class	FiniteStateMachine.Transition A handle used for controlling the transition of the FiniteStateMachine.
static class	FiniteStateMachine.UnallowedTransitionException If a transition is not allowed to happen.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FiniteStateMachine(com.google.common.collect.SetMultimap<T,T> allowedTransitions, Set<T> universalEnds, T errorState, T initialState)

Method Summary

Modifier and Type	Method and Description
FiniteStateMachine<T>	cloneAtCurrentState()
FiniteStateMachine<T>	cloneAtInitialState()
T	getCurrentState() Get the current state.
protected boolean	isAllowedTransition(T startState, T endState)
FiniteStateMachine.Transition	startTransition(T endState) Start a transition to the end state specified.
boolean	transitionIfAllowed(T endState) Transition immediately to the given end state if the transition is allowed.
void	transitionImmediately(T endState) Transition immediately to the given end state.

Methods inherited from class java.lang.Object

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

Constructor Detail

FiniteStateMachine

protected FiniteStateMachine(com.google.common.collect.SetMultimap<T,T> allowedTransitions,
                             Set<T> universalEnds,
                             T errorState,
                             T initialState)

Method Detail

startTransition

public FiniteStateMachine.Transition startTransition(T endState)
                                              throws FiniteStateMachine.UnallowedTransitionException,
                                                     InterruptedException

Start a transition to the end state specified. The returned FiniteStateMachine.Transition object is a closeable that will finalize the transition when it is closed. While the transition is open, no other transition can start. It is recommended to call this method only within a try-with-resource block to ensure the transition is closed.

Throws:

FiniteStateMachine.UnallowedTransitionException - If the transition is not allowed.

InterruptedException - if the thread got interrupted while waiting for a non-transitioning state.

transitionImmediately

public void transitionImmediately(T endState)
                           throws FiniteStateMachine.UnallowedTransitionException,
                                  InterruptedException,
                                  FiniteStateMachine.FailedTransitionCallbackException

Transition immediately to the given end state. This is essentially startTransition(Object) immediately followed by FiniteStateMachine.Transition.close().

Throws:

FiniteStateMachine.UnallowedTransitionException - if the transition is not allowed.

InterruptedException - if the thread got interrupted while waiting for a non-transitioning state.

FiniteStateMachine.FailedTransitionCallbackException

transitionIfAllowed

public boolean transitionIfAllowed(T endState)
                            throws InterruptedException,
                                   FiniteStateMachine.FailedTransitionCallbackException

Transition immediately to the given end state if the transition is allowed.

Returns:

true if the transition happened.

Throws:

InterruptedException - if the thread got interrupted while waiting for a non-transitioning state.

FiniteStateMachine.FailedTransitionCallbackException

getCurrentState

public T getCurrentState()
                  throws InterruptedException

Get the current state. This method will wait until the FSM is in a non-transitioning state (although a transition may start immediately after).

Throws:

InterruptedException - if the thread got interrupted while waiting for a non-transitioning state.

cloneAtInitialState

public FiniteStateMachine<T> cloneAtInitialState()

Returns:

A clone of this FSM starting at the initial state of the FSM.

cloneAtCurrentState

public FiniteStateMachine<T> cloneAtCurrentState()
                                          throws InterruptedException

Returns:

A clone of this FSM starting at the current state of the FSM.

Throws:

InterruptedException

isAllowedTransition

protected boolean isAllowedTransition(T startState,
                                      T endState)