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 UI thread as resolved by Dispatcher. 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 on the UI thread.

The onStarted handlers are guaranteed to be called on the UI thread before the background task executes, and the onDone handlers are guaranteed to be called after the background task completes.

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

There are two ways to use this class:

• Builder-only: pass a task and wire handlers via the builder.
• Handler interfaces: implement one of the handler interfaces (ProgressWorker.TaskHandler, ProgressWorker.ResultTaskHandler, ProgressWorker.ProgressTaskHandler, ProgressWorker.ProgressResultTaskHandler) to encapsulate both the background task and its handlers in a single class. Handler interface methods are wired automatically and called first. Additional handlers can then be added via the builder and are called after.

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

Builder based usage example:

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

See Also:

• builder()
• ProgressWorker.Handler

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ProgressWorker.Builder<T,V>	Builds a ProgressWorker instance.
static interface	ProgressWorker.BuilderFactory	Provides builders for a given task type.
static interface	ProgressWorker.Handler	Provides default handler methods for the ProgressWorker lifecycle.
static interface	ProgressWorker.ProgressHandler<V>	Extends ProgressWorker.Handler with progress and publish handlers.
static interface	ProgressWorker.ProgressReporter<V>	Reports progress and publishes intermediate results for a ProgressWorker
static interface	ProgressWorker.ProgressResultTask<T,V>	A progress aware background task producing a result.
static interface	ProgressWorker.ProgressResultTaskHandler<T,V>	A ProgressWorker.ProgressResultTask combined with ProgressWorker.ProgressHandler, for encapsulating a progress-aware, result-producing background task and its handlers in a single class.
static interface	ProgressWorker.ProgressTask<V>	A progress aware background task.
static interface	ProgressWorker.ProgressTaskHandler<V>	A ProgressWorker.ProgressTask combined with ProgressWorker.ProgressHandler, for encapsulating a progress-aware background task and its handlers in a single class.
static interface	ProgressWorker.ResultTask<T>	A background task producing a result.
static interface	ProgressWorker.ResultTaskHandler<T>	A ProgressWorker.ResultTask combined with ProgressWorker.Handler, for encapsulating a result-producing background task and its handlers in a single class.
static interface	ProgressWorker.Task	A background task.
static interface	ProgressWorker.TaskHandler	A ProgressWorker.Task combined with ProgressWorker.Handler, for encapsulating a background task and its handlers in a single class.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_MAXIMUM

Method Summary

Modifier and Type	Method	Description
static ProgressWorker.BuilderFactory	builder()
boolean	cancel(boolean mayInterruptIfRunning)	Attempts to cancel the background task.
boolean	cancelled()
boolean	done()
void	execute()	Executes this worker, running the task on a background thread and its handlers on the UI thread.
@Nullable T	get()	Waits if necessary for the task to complete, and returns its result.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_MAXIMUM

public static final int DEFAULT_MAXIMUM

See Also:

• Constant Field Values

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 on the UI thread.

Must be called on the UI thread, since the Dispatcher handler executor is resolved for the current context at this point (relevant for platforms with a per-context UI thread).

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel the background task.

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.

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