Package com.complexible.common.base

# Class AtomicState<S extends Enum<S>>

java.lang.Object
com.complexible.common.base.AtomicState<S>

public class AtomicState<S extends Enum<S>> extends Object
Represents a mutable state that can be updated exclusively through `beginTransitionFrom(Enum[])` and `endTransition()` calls. Actual states are represented as enumerations. This class guarantees that there will be a single current state at any time and at most one state transition action will be running at any time.

Since:
  2.0.3
Version:
  3.0
Author:
  Evren Sirin

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AtomicState(S theInitState)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `S`
  `beginTransitionFrom(S... theStates)`
  Starts a transition provided that the current state is one of the specified states.
  `void`
  `cancelTransition()`
  Request the cancellation of current transition.
  `void`
  `checkState(Collection<S> theStates)`
  Throws `IllegalStateException` if the current state is one of the given states.
  `void`
  `checkState(S theState)`
  Throws `IllegalStateException` if the current state is not equal to the given state.
  `void`
  `checkStateNot(S theState)`
  Throws `IllegalStateException` if the current state is equal to the given state.
  `void`
  `endTransition()`
  Ends the current transition.
  `void`
  `endTransition(S theFinalState)`
  Ends the transition with the given final state.
  `S`
  `get()`
  Returns the current state.
  `boolean`
  `isInTransition()`
  Returns `true` if a transition is being performed.
  `boolean`
  `isTransitionCanceled()`
  Returns `true` if the current transition is requested to be canceled.
  `static <S extends Enum<S>>
  AtomicState<S>`
  `newState(S theInitState)`
  `void`
  `set(S theState)`
  Sets the current state only if the current thread `began` a transition.
  `void`
  `transitionTo(S theFinalState, S... theInitialStates)`
  Performs the transition to a final state.
  `S`
  `tryBeginTransition(S... thePossibleInitialStates)`
  Attempts to start a transition "tentatively": that is, it will attempt the transition only if the current state is contained in `thePossibleInitialStates`; If it is not, this will unroll any action taken, as if the transition was never attempted.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### AtomicState

    public AtomicState(S theInitState)

- ## Method Details

  - ### newState

    public static <S extends Enum<S>> AtomicState<S> newState(S theInitState)

  - ### beginTransitionFrom

    public S beginTransitionFrom(S... theStates)
    Starts a transition provided that the current state is one of the specified states. If no initial states are provided then the transition will begin regardless of the current state. This call will block if a current transition is in progress.
    Throws:
      `IllegalStateException` - if the current state is not a valid initial state for the action

  - ### tryBeginTransition

    public S tryBeginTransition(S... thePossibleInitialStates)
    Attempts to start a transition "tentatively": that is, it will attempt the transition only if the current state is contained in `thePossibleInitialStates`; If it is not, this will unroll any action taken, as if the transition was never attempted. If the transition is successful, then the old state will be returned. If it is not successful, then `null` is returned. This is an inexpensive way of doing idempotent transitions (i.e. only transition to a single state once).
    Parameters:
      `thePossibleInitialStates` - the possible states that the transaction can be in
    Returns:
      the old state, if the transition has begun, or `null` if the transition fails

  - ### endTransition

    public void endTransition(S theFinalState)
    Ends the transition with the given final state. This is equivalent to: `try { set(theFinalState); } finally { endTransition(); }`
    Parameters:
      `theFinalState` - the final state

  - ### endTransition

    public void endTransition()
    Ends the current transition.

  - ### transitionTo

    public void transitionTo(S theFinalState, S... theInitialStates)
    Performs the transition to a final state. This is equivalent to: `beginTransitionFrom(theInitialStates); try { set(theFinalState); } finally { endTransition(); }`
    Parameters:
      `theFinalState` -
      `theInitialStates` -

  - ### cancelTransition

    public void cancelTransition()
    Request the cancellation of current transition.

  - ### isTransitionCanceled

    public boolean isTransitionCanceled()
    Returns `true` if the current transition is requested to be canceled.

  - ### get

    public S get()
    Returns the current state.

  - ### set

    public void set(S theState)
    Sets the current state only if the current thread `began` a transition.

  - ### checkState

    public void checkState(S theState)
    Throws `IllegalStateException` if the current state is not equal to the given state.

  - ### checkState

    public void checkState(Collection<S> theStates)
    Throws `IllegalStateException` if the current state is one of the given states.

  - ### checkStateNot

    public void checkStateNot(S theState)
    Throws `IllegalStateException` if the current state is equal to the given state.

  - ### isInTransition

    public boolean isInTransition()
    Returns `true` if a transition is being performed.