Package com.kosdev.kos.commons.util.ready

Class ReadyIndicator

java.lang.Object
com.kosdev.kos.commons.util.ready.ReadyIndicator
public class ReadyIndicator extends Object
Class used by Ready beans to indicate when the bean has become ready.
Since:
1
Version:
9
See Also:

  • Constructor Details

    • ReadyIndicator

      public ReadyIndicator()

  • Method Details

    • addState

      public void addState(Object state)
      Add a state object that must be marked ready before the indicator is ready. Every specified state object must have a corresponding call to setStateReady(state) , in addition to the standard call to setReady() for this indicator to become ready.

      This is useful for objects that should only become ready when their normal setReady() call has been made, such as when called from BeanContext when all dependencies are ready, in addition to some internal initialization process completes, which calls setStateReady(state) . This allows any number of states to be defines before the object becomes ready.

      Calls to addState() must occur before the indicator is ready to have any effect.

      Parameters:
      state - the object used to represent the state that is being tracked
      Since:
      1

    • setReady

      public void setReady()
      Call this method to indicate that the indicator is ready. If there are no pending states from calling addState() then the indicator will be marked ready which will:
      1. Set the ready flag to true
      2. Call the onReady() method on each callback object
      3. Clear the list of callbacks
      If any states are still waiting to be marked ready, this will simply return after tracking that setReady() has been called.
      Since:
      1

    • setStateReady

      public void setStateReady(Object state)
      Call this method to indicate that the specified state is ready, where state corresponds to a addState(state) call. This will remove the state from the pending list of states for this indicator. If this is the last state and setReady() has already been called, the indicator will be marked ready which will:
      1. Set the ready flag to true
      2. Call the onReady() method on each callback object
      3. Clear the list of callbacks
      If any states are still waiting to be marked ready, or setReady() has not been called, this will simply return after removing the state from the pending list.
      Parameters:
      state - a state object equal to a state provided to addState()
      Since:
      1

    • isReady

      public boolean isReady()
      Indicates if the attached bean is ready or not.
      Returns:
      true if this bean is ready, otherwise false
      Since:
      1

    • isReady

      public boolean isReady(ReadyCallback callback)
      Returns true if the indicator is ready. If not, the callback will be queued and called when the indicator becomes ready. Unlike whenReady() , this will only use the callback if the indicator is not currently ready.
      Returns:
      true if ready; if not, add the given callback to the list
      Since:
      1

    • whenReady

      public void whenReady(ReadyCallback callback)
      Calls the specified callback when ready. If already ready, then the callback is called immediately, otherwise it will be called when the indicator becomes ready. The callback will be called at most one time. Once called, the callback will be removed from the indicator. If the indicator resets and becomes ready again, this callback will not be called a second time. For this use case, use whenReadyRecurring(com.kosdev.kos.commons.util.ready.ReadyCallback) .
      Parameters:
      callback - called when the indicator becomes ready
      Since:
      1

    • whenReadyRecurring

      public void whenReadyRecurring(ReadyCallback callback)
      Calls the specified callback when ready. If already ready, then the callback is called immediately, otherwise it will be called when the indicator becomes ready. The callback will be retained by the indicator and will be called again if the indicator is reset and becomes ready again. This callback can removed using remove(com.kosdev.kos.commons.util.ready.ReadyCallback) .

      Most indicators, such as when used in a service, only become ready a single time. For these use cases, use whenReady(com.kosdev.kos.commons.util.ready.ReadyCallback) as it doesn't retain a reference to the callback unless the service never becomes ready. This limits the need to remove callbacks in cleanup code paths.

      Parameters:
      callback - called when the indicator becomes ready
      Since:
      9

    • whenReset

      public void whenReset(ReadyIndicator.ResetCallback callback)
      Add a reset callback. This will be called any time the indicator is reset. As callbacks are retained in the indicator, if there is a need to remove the callback, use remove(com.kosdev.kos.commons.util.ready.ReadyIndicator.ResetCallback) .
      Parameters:
      callback - called when the indicator is reset
      Since:
      9

    • reset

      public void reset()
      Reset the indicator so that is can become ready again. If the indicator originally used multiple states to become ready, the states are not restored, meaning that the indicator will become ready on the next call to setReady() . If states need to be restored, use a ResetCallback to add the states back when the indicator is reset.

      If the indicator is not ready, this will be ignored as there is nothing to reset.

      Resetting an indicator will call any attached reset callbacks.

    • remove

      public void remove(ReadyCallback callback)
      Remove the ReadyCallback from the ready lists.
      Parameters:
      callback - the callback to remove
      Since:
      9

    • remove

      public void remove(ReadyIndicator.ResetCallback callback)
      Remove the ResetCallback from the reset list.
      Parameters:
      callback - the callback to remove
      Since:
      9

    • waitUntilReady

      public void waitUntilReady()
      Block the caller until ready.
      Since:
      1