Package com.globalmentor.model

Class PollStateManager<S>

  • Type Parameters:
    S - The type of state being managed.
    public class PollStateManager<S>
extends java.lang.Object
    Manages a sequence of several states, allowing a consumer to poll for states, with state transitions occurring when needed. For example, this manager may keep track of a number of image transition delays, increasing the delay after some amount of time has passed.

    For each state, a minimum duration and a minimum number of polls may be supplied. A state will only transition after the minimum duration has passed and the requested minimum number of polls has occurred. After the maximum duration or maximum poll count is reached, a transition always occurs. Once the last state is reached, the state will not transition regardless of duration or polls.

    The same state may occur several times in the sequence.

    State transition does not occur asynchronously; the current state will be determined only when queried.

    If there is at least one state defined, getState() and pollState() will never return null.

    This class is thread-safe.

    Author:
    Garret Wilson

    • Constructor Summary

      Constructors 
      Constructor Description
      PollStateManager()
      Default constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addMaxDurationState​(S state, long maxDuration)
      Adds a new state at the end of the sequence of states being managed, with a maximum duration before transition.
      void addMaxPollCountState​(S state, long maxPollCount)
      Adds a new state at the end of the sequence of states being managed, with a maximum poll count before transition.
      void addState​(S state, long maxDuration, long maxPollCount)
      Adds a new state at the end of the sequence of states being managed.
      void addState​(S state, long minDuration, long maxDuration, long minPollCount, long maxPollCount)
      Adds a new state at the end of the sequence of states being managed.
      S getState()
      Retrieves the current state.
      long getStateDuration()
      Determines the amount of time the current state has been in effect.
      protected com.globalmentor.model.PollStateManager.StateInfo getStateInfo()  
      long getStateRemainingDuration()
      Determines the amount of time the current state has remaining to be in effect before its maximum duration.
      boolean hasNextState()
      Determines whether there exists states after the current state, if any.
      boolean isTransitionReady()
      Determines if a transition should occur based upon the current duration and poll count of the current state.
      S pollState()
      Polls and then retrieves the current state.
      S reset()
      Resets the poll manager to the first state in the sequence.
      S resetState()
      Resets the information for the current state by setting the poll count to zero and initializing the time to the current time.
      protected com.globalmentor.model.PollStateManager.StateInfo transition()
      Transitions to the next state in the sequence.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • PollStateManager

        public PollStateManager()
        Default constructor.

    • Method Detail

      • addMaxDurationState

        public void addMaxDurationState​(S state,
                                long maxDuration)
        Adds a new state at the end of the sequence of states being managed, with a maximum duration before transition.
        Parameters:
        state - The state.
        maxDuration - The maximum duration, in milliseconds, for a transition, regardless of polls.
        Throws:
        java.lang.NullPointerException - if the given state is null.

      • addMaxPollCountState

        public void addMaxPollCountState​(S state,
                                 long maxPollCount)
        Adds a new state at the end of the sequence of states being managed, with a maximum poll count before transition.
        Parameters:
        state - The state.
        maxPollCount - The maximum number of polls before a transition, regardless of duration.
        Throws:
        java.lang.NullPointerException - if the given state is null.

      • addState

        public void addState​(S state,
                     long maxDuration,
                     long maxPollCount)
        Adds a new state at the end of the sequence of states being managed. Either the maximum duration or maximum poll count will cause the state to transition.
        Parameters:
        state - The state.
        maxDuration - The maximum duration, in milliseconds, for a transition, regardless of polls.
        maxPollCount - The maximum number of polls before a transition, regardless of duration.
        Throws:
        java.lang.NullPointerException - if the given state is null.

      • addState

        public void addState​(S state,
                     long minDuration,
                     long maxDuration,
                     long minPollCount,
                     long maxPollCount)
        Adds a new state at the end of the sequence of states being managed.
        Parameters:
        state - The state.
        minDuration - The minimum duration, in milliseconds, before a transition.
        maxDuration - The maximum duration, in milliseconds, for a transition, regardless of polls.
        minPollCount - The minimum number of polls before a transition.
        maxPollCount - The maximum number of polls before a transition, regardless of duration.
        Throws:
        java.lang.NullPointerException - if the given state is null.

      • getStateInfo

        protected com.globalmentor.model.PollStateManager.StateInfo getStateInfo()
        Returns:
        Info for the current state, or null if no states are defined.

      • hasNextState

        public boolean hasNextState()
        Determines whether there exists states after the current state, if any.
        Returns:
        true if there exists states after the current state, if any, or false if there are no further states or no states are defined.

      • getStateDuration

        public long getStateDuration()
        Determines the amount of time the current state has been in effect. This method does not transition the state, so the returned duration may be longer than the maximum duration for the current state.
        Returns:
        The amount of time, in milliseconds, the current state has been in effect, or -1 if no states are defined.

      • getStateRemainingDuration

        public long getStateRemainingDuration()
        Determines the amount of time the current state has remaining to be in effect before its maximum duration. This value may be negative if the state has been in effect longer than its maximum allowed.
        Returns:
        The amount of time, in milliseconds, the current state has remaining to be in effect, or Long.MAX_VALUE if no states are defined.

      • getState

        public S getState()
        Retrieves the current state. The current poll count is not affected, but if sufficient time has passed the state may first transition because of duration.
        Returns:
        The current state, or null if no states are defined.

      • pollState

        public S pollState()
        Polls and then retrieves the current state. The state is transitioned if the increased poll count or duration requires.
        Returns:
        The current state, or null if no states are defined.

      • isTransitionReady

        public boolean isTransitionReady()
        Determines if a transition should occur based upon the current duration and poll count of the current state. Specifically, transition should occur if either the duration or the poll count is above the current maximum, or both are above their minimums.
        Returns:
        true if this state should transition, or null if there are no states or the current state is the last state.
        See Also:
        hasNextState()

      • transition

        protected com.globalmentor.model.PollStateManager.StateInfo transition()
        Transitions to the next state in the sequence. The new state is reset. If there are no further states in the sequence, no action occurs.
        Returns:
        Information on the new state, or null if no states are defined.

      • reset

        public S reset()
        Resets the poll manager to the first state in the sequence. That state's information will be reset.
        Returns:
        The new state, or null if no states are defined.
        See Also:
        resetState()

      • resetState

        public S resetState()
        Resets the information for the current state by setting the poll count to zero and initializing the time to the current time. If no states are defined, no action occurs.
        Returns:
        The current state, or null if no states are defined.