Package com.complexible.common.base

Class AtomicState<S extends java.lang.Enum<S>>

  • public class AtomicState<S extends java.lang.Enum<S>>
extends java.lang.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

      All Methods Static Methods Instance Methods Concrete Methods 
      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​(java.util.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 java.lang.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 Detail

      • AtomicState

        public AtomicState​(S theInitState)

    • Method Detail

      • newState

        public static <S extends java.lang.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:
        java.lang.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:
        theInitialStates -
        theFinalState -

      • 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​(java.util.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.