com.virtuosotechnologies.lib.asyncjob
Interface AsyncJob

All Known Implementing Classes:

AbstractAsyncJob

public interface AsyncJob

A job that can be run asynchronously.

The job should implement run() to actually perform the task in the current thread, and interrupt() to interrupt the currently running job. Each AsyncJob object can be run multiple times in sequence, but may not be used multiple times simultaneously; thus, it is well-defined which job the interrupt() method should interrupt.

AsyncJob also contains a PropertySet, which is used to provide meta-information to a job runner; for instance, whether the job may be canceled.

Most AsyncJobs can extend AbstractAsyncJob. Another likely use of AsyncJob is to create a proxy AsyncJob wrapping a remote method call.

Field Summary

static ClassConstrainedKey	CAN_CANCEL_PROPERTY Key for well-known "can cancel" property.
static ClassConstrainedKey	COMPLETED_PROGRESS_STRING_PROPERTY Key for well-known "completed progress string" property.
static ClassConstrainedKey	FAILED_PROGRESS_STRING_PROPERTY Key for well-known "failed progress string" property.
static float	INDETERMINATE_PROGRESS Special value for indicating indeterminate progress.
static ClassConstrainedKey	INITIAL_FRACTION_DONE_PROPERTY Key for well-known "initial fraction done" property.
static ClassConstrainedKey	INITIAL_PROGRESS_STRING_PROPERTY Key for well-known "initial progress string" property.
static ClassConstrainedKey	JOB_NAME_PROPERTY Key for well-known job name property.
static ClassConstrainedKey	PRESTART_PROGRESS_STRING_PROPERTY Key for well-known "pre-start progress string" property.

Method Summary

PropertySet	getProperties() Get the properties for this AsyncJob.
boolean	interrupt(AsyncJobException exception) Interrupt the job if it is currently running.
Object	run(AsyncJobProgressReporter reporter) Run a job and report progress.

Field Detail

INDETERMINATE_PROGRESS

public static final float INDETERMINATE_PROGRESS

Special value for indicating indeterminate progress. This value is used by the AsyncJob to report indeterminate progress in AsyncJobProgressReporter, and can also be compared with the value reported in an AsyncJobProgressEvent sent to an AsyncJobListener.

See Also:

Constant Field Values

JOB_NAME_PROPERTY

public static final ClassConstrainedKey JOB_NAME_PROPERTY

Key for well-known job name property. Class is String. The default is "Please Wait..."

CAN_CANCEL_PROPERTY

public static final ClassConstrainedKey CAN_CANCEL_PROPERTY

Key for well-known "can cancel" property. Class is Boolean. The default is false.

INITIAL_FRACTION_DONE_PROPERTY

public static final ClassConstrainedKey INITIAL_FRACTION_DONE_PROPERTY

Key for well-known "initial fraction done" property. Class is Float. The default is 0.0f.

INITIAL_PROGRESS_STRING_PROPERTY

public static final ClassConstrainedKey INITIAL_PROGRESS_STRING_PROPERTY

Key for well-known "initial progress string" property. Class is String. The default is "".

PRESTART_PROGRESS_STRING_PROPERTY

public static final ClassConstrainedKey PRESTART_PROGRESS_STRING_PROPERTY

Key for well-known "pre-start progress string" property. Class is String. The default is "".

COMPLETED_PROGRESS_STRING_PROPERTY

public static final ClassConstrainedKey COMPLETED_PROGRESS_STRING_PROPERTY

Key for well-known "completed progress string" property. Class is String. The default is "".

FAILED_PROGRESS_STRING_PROPERTY

public static final ClassConstrainedKey FAILED_PROGRESS_STRING_PROPERTY

Key for well-known "failed progress string" property. Class is String. The default is "".

Method Detail

getProperties

public PropertySet getProperties()

Get the properties for this AsyncJob. The PropertySet is not modifiable because generally the only entity that should be setting these properties is the AsyncJob itself.

Returns:

a PropertySet containing the properties

run

public Object run(AsyncJobProgressReporter reporter)
           throws AsyncJobException

Run a job and report progress. The task should be run in the current thread. Generally, each object should assume it is responsible for only one execution at a time, so if this method is called when an execution is already going on, it should throw IllegalStateException.

Parameters:

reporter - AsyncJobProgressReporter for the job

Returns:

a result object

Throws:

AsyncJobException - job failed

IllegalStateException - job is already running.

interrupt

public boolean interrupt(AsyncJobException exception)

Interrupt the job if it is currently running. The implementation should respond by throwing the given AsyncJobException out of run. If no custom exception is specified, the job should throw a new AsyncJobInterruptedException. If the job is not running, has already finished running, or is currently running but cannot be interrupted, this method should return false. Returning true should constitute a guarantee that an exception will be thrown out of the run method. Note that this method and the run method will typically be called from different threads, so make sure they are appropriately synchronized.

Parameters:

exception - custom exception to throw

Returns:

true if the job was interrupted. Return false if the job was not running or cannot be interrupted.