Class CoalescingTaskScheduler

java.lang.Object
org.jjazz.utilities.api.CoalescingTaskScheduler
public final class CoalescingTaskScheduler extends Object
Call a task after a delay.

- User can call request(Runnable task) repeatedly
- Runs the *last* Runnable only, after delayMs without new requests (debounce mode) or within a fixed window (throttle mode)

By default, the Runnable executes on the scheduler thread. If you need EDT execution, wrap the Runnable: () -> SwingUtilities.invokeLater(...).

Thread-safe: all public methods can be called from any thread.

  • Constructor Details

    • CoalescingTaskScheduler

      public CoalescingTaskScheduler(long delayMs)
      Create a CoalescingTaskScheduler with default settings (debounce mode, logging exceptions).
      Parameters:
      delayMs - The delay in milliseconds before executing the task
      Throws:
      IllegalArgumentException - if delayMs is negative

    • CoalescingTaskScheduler

      public CoalescingTaskScheduler(long delayMs, Consumer<Throwable> exceptionHandler)
      Create a CoalescingTaskScheduler with custom exception handling.
      Parameters:
      delayMs - The delay in milliseconds before executing the task
      exceptionHandler - Optional handler for exceptions thrown by scheduled tasks. If null, exceptions are logged at WARNING level.
      Throws:
      IllegalArgumentException - if delayMs is negative

    • CoalescingTaskScheduler

      public CoalescingTaskScheduler(long delayMs, boolean restartDelayOnNewRequest, Consumer<Throwable> exceptionHandler)
      Create a CoalescingTaskScheduler with full configuration.
      Parameters:
      delayMs - The delay in milliseconds before executing the task
      restartDelayOnNewRequest - If true (debounce mode): each new request resets the delay timer. If false (throttle mode): the first request starts a fixed delay window, subsequent requests only update the task to run.
      exceptionHandler - Optional handler for exceptions thrown by scheduled tasks. If null, exceptions are logged at WARNING level.

  • Method Details

    • request

      public void request(Runnable action)
      Schedule action to run after delayMs.

      Any exception thrown by the action will be handled by the configured exception handler, or logged if no handler was provided.

      Parameters:
      action - The task to execute

    • cancel

      public void cancel()
      Cancel any pending action.

      After this call, no task will execute unless request() is called again.

    • hasPendingTask

      public boolean hasPendingTask()
      Check if there is a task currently scheduled to run.

      Note: This method returns a snapshot of the current state. By the time the caller acts on this information, the state may have changed.

      Returns:
      true if a task is scheduled and has not yet executed or been cancelled

    • getDelayMs

      public long getDelayMs()
      Get the configured delay in milliseconds.
      Returns:
      the delay before task execution

    • isRestartDelayOnNewRequest

      public boolean isRestartDelayOnNewRequest()
      Check if the scheduler is in debounce mode (restarting delay on each request).
      Returns: