Module is.codion.common.model
Package is.codion.common.model.worker

Class ProgressWorker<T,V>

java.lang.Object
is.codion.common.model.worker.ProgressWorker<T,V>
Type Parameters:
T - the type of result this ProgressWorker produces.
V - the type of intermediate result produced by this ProgressWorker
public final class ProgressWorker<T,V> extends Object

Executes a task on a background thread, invoking its lifecycle handlers on the dispatch context resolved by Dispatcher — the UI thread on UI platforms, which is what the documentation below calls it. Instances of this class are not reusable.

Each execution runs on its own thread from a shared pool of daemon threads, created as needed and reaped when idle, so N simultaneous executions use N threads.

Note that this implementation does NOT coalesce progress reports or intermediate result publishing, but simply pushes those directly to the onProgress and onPublish handlers for the Dispatcher.

The onStarted handlers are guaranteed to be called using the Dispatcher before the background task executes, and the onDone handlers after the background task completes or, when cancelled, as soon as it is cancelled, while it may still be running (see cancel(boolean)).

All handler types support multiple handlers, which are called in the order they were added.

A handler throwing an exception neither prevents the remaining handlers from being called nor changes the outcome. Once all handlers have been called, the first exception thrown by a handler is rethrown on the dispatch thread, with any others added as suppressed. An exception thrown by the task without any onException handler is rethrown the same way, taking precedence over any handler exceptions.

There are two ways to use this class:

On successful completion, handlers are called in this order: onDone → onSuccess → onResult(T) (result-producing tasks only).

Builder based usage example: 

ProgressWorker.builder()
				.task(this::performTask)
				.onStarted(this::displayDialog)
				.onDone(this::closeDialog)
				.onWorking(this::setBusy)
				.onSuccess(this::handleSuccess)
				.onResult(this::handleResult)
				.onProgress(this::displayProgress)
				.onPublish(this::publishMessage)
				.onCancelled(this::displayCancelledMessage)
				.onException(this::displayException)
				.execute();
See Also:

  • Field Details

  • Method Details

    • builder

      public static ProgressWorker.BuilderFactory builder()
      Returns:
      a ProgressWorker.BuilderFactory

    • execute

      public void execute()
      Executes this worker, running the task on a background thread and its handlers using the Dispatcher.

      Must be called where a dispatch context is bound (Dispatcher.bound()), since the handler executor is resolved for the caller at this point, and implementations binding a context per request or session must resolve the right one.

      Throws:
      IllegalStateException - if no dispatch context is bound (except when using Dispatcher.SYNCHRONOUS) or if this worker has already been executed

    • cancel

      public boolean cancel(boolean mayInterruptIfRunning)
      Attempts to cancel the background task.

      The onDone and onCancelled handlers are called as soon as the task is cancelled, while it may still be running, until it notices the interruption or completes. Its result is discarded, and any progress it reports or chunks it publishes once cancelled are dropped.

      Parameters:
      mayInterruptIfRunning - true if the thread executing the task should be interrupted
      Returns:
      false if the task could not be cancelled, typically because it has already completed

    • cancelled

      public boolean cancelled()
      Returns:
      true if this task was cancelled before it completed

    • done

      public boolean done()
      Returns:
      true if this task has completed, whether normally, via an exception or cancellation

    • get

      public @Nullable T get() throws InterruptedException, ExecutionException
      Waits if necessary for the task to complete, and returns its result.

      Always returns null for ProgressWorker.Task and ProgressWorker.ProgressTask workers, which produce no result.

      Returns:
      the task result
      Throws:
      InterruptedException - if the current thread was interrupted while waiting
      ExecutionException - if the task threw an exception
      CancellationException - if the task was cancelled
      IllegalStateException - if called where the dispatch context is bound before the task is done, which would block the dispatch thread, or deadlock waiting for any onStarted handlers to run