Package com.tccc.kos.commons.util

Class Pause

java.lang.Object
com.tccc.kos.commons.util.Pause
public class Pause extends Object
A Pause provides a simple way to allow an object to be externally paused / resumed. For example, consider a motor that should not run when the door is open. The motor can use a Pause to determine if the motor is safe to run and the door can interact with the Pause instead of the motor itself. This is such a common pattern in control systems that it is abstracted into a reusable class.

A Pause tracks a number of pause reasons. As long as any reasons exist, the Pause is paused. Once all the reasons are removed the Pause will resume. A reason can be any object, but reasons are not reference counted. That is, if a reason is added more than once, it counts as a single reason and the first call to remove will remove it.

The implementation provides the ability to query the pause state as well as register listeners to be notified when the pause state changes.

Since:
1.0
Version:
2023-02-27

  • Constructor Details

    • Pause

      public Pause(String name)

  • Method Details

    • isPaused

      public boolean isPaused()
      Return true if the Pause is paused. This will be true if there are any pause reasons.
      Returns:
      true if the Pause is paused

    • addReason

      public void addReason(Object reason)
      Add a reason for the Pause to be paused. If not paused, the addition of the reason will cause it to become paused. Reasons are not reference counted so adding the same reason object more than once does not increment the pause count.
      Parameters:
      reason - the reason to pause

    • removeReason

      public void removeReason(Object reason)
      Remove a reason from the Pause . If this is the last remaining reason then the Pause will resume.
      Parameters:
      reason - the reason to remove

    • addPauseListener

      public void addPauseListener(PauseListener listener, boolean callListener)
      Add a listener to the Pause to be notified of pause state changes.
      Parameters:
      listener - the listener to add
      callListener - if true, call the listener immediately based on the current state

    • addResumeListener

      public void addResumeListener(ResumeListener listener, boolean callListener)
      Add a listener to the Pause to be notified of resume state changes.
      Parameters:
      listener - the listener to add
      callListener - if true, call the listener immediately based on the current state

    • removeListener

      public void removeListener(BasePauseListener listener)
      Remove a listener from the Pause .
      Parameters:
      listener - the listener to remove

    • getReasons

      public Collection<Object> getReasons()
      Return the list of pause reasons. These are the actual objects that were used to pause the Pause . These are typically not very human-friendly. Use getPauseReasonStrings() to return a list of strings which are more useful for diagnostics / debugging.
      Returns:
      the list of all active reasons

    • getPauseReasonStrings

      public Collection<String> getPauseReasonStrings()
      Return a list of pause reasons converted to more human-readable strings. By default this will return the class names of the reasons, but if the object implements PauseReason then it can return a custom string to use in this call. This can be useful if the pause reasons need to be logged or returned via endpoint as this prevents the objects from being serialized, but still allows control over how they appear.
      Returns:
      the list of reasons converted to strings