oracle.javatools.parser.util
Class AsyncTask

java.lang.Object
  oracle.javatools.parser.util.AsyncTask

All Implemented Interfaces:

java.lang.Runnable

public abstract class AsyncTask
extends java.lang.Object
implements java.lang.Runnable

The AsyncTask is a part of a basic API to allow scheduling asynchronous tasks that support cancelling while the task is running. It is recommended that JSR 166 be used when it becomes available as part of the JDK later.

The process of notifying a running task that a cancellation has been requested (and it should abort) is implementation-specific. For example, the following is a possible implementation:

   private boolean _isCancelled = false;
   protected void requestCancelImpl()
   {
     _isCancelled = true;
   }
   protected boolean isCancelledImpl()
   {
    return _isCancelled;
   }
 

Within runImpl(), the implementation could then call bailIfCancelled() periodically to bail out of the task if it has been marked for cancellation. Note, it is the implementation's responsibility to ensure that any acquired locks or resources are properly released in case of task cancellation.

Nested Class Summary

static class

AsyncTask.CancelledException The CancelledException is used to bail out of a running task.

Field Summary

protected static java.lang.String	CANCELLED_RESULT Tasks that are cancelled successfully in-progress should return this cancelled result, so that the task status can be updated accordingly.
static int	STATUS_CANCELLED Constant for cancelled status.
static int	STATUS_COMPLETED Constant for completed successfully status.
static int	STATUS_FAILED Constant for completed w/ failed status due to RuntimeException.
static int	STATUS_READY Constant for ready-to-run status.
static int	STATUS_RUNNING Constant for currently running status.

Constructor Summary

protected

AsyncTask() Set up the AsyncTask in ready-to-run mode.

Method Summary

protected void	bailIfCancelled() Checks if the task has been marked for cancellation, and throws a CancelledException if it has.
java.lang.Object	getResult() Fetch the completed result of the task (if any).
int	getStatus() Fetches the current status of the task.
protected abstract boolean	isCancelledImpl() Return whether the task is marked for cancellation, to be implemented by the implementation.
boolean	isFinished() Fetch whether this task is completed or not.
protected void	requestCancel() Request to cancel the task.
protected abstract void	requestCancelImpl() Request to cancel the task in-progress, to be implemented by the implementation.
void	run() Performs the task.
protected abstract java.lang.Object	runImpl() Implementation of the task.
protected static void	sleep(int ms) Utility routine to sleep for the given amount of time.
void	waitUntilFinished() Waits until the task is finished (i.e., isFinished() returns true).
void	waitUntilFinished(int ms) Waits until the task is finished (i.e., isFinished() returns true).

Methods inherited from class java.lang.Object

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

Field Detail

STATUS_READY

public static final int STATUS_READY

Constant for ready-to-run status.

See Also:

Constant Field Values

STATUS_RUNNING

public static final int STATUS_RUNNING

Constant for currently running status.

See Also:

Constant Field Values

STATUS_COMPLETED

public static final int STATUS_COMPLETED

Constant for completed successfully status. The return result of getResult() is the return result of runImpl().

See Also:

Constant Field Values

STATUS_FAILED

public static final int STATUS_FAILED

Constant for completed w/ failed status due to RuntimeException. The runtime exception can be retrieved w/ getResult().

See Also:

Constant Field Values

STATUS_CANCELLED

public static final int STATUS_CANCELLED

Constant for cancelled status. There is no guarantee as to whether the task was started or cancelled mid-progress. There is no return result.

See Also:

Constant Field Values

CANCELLED_RESULT

protected static final java.lang.String CANCELLED_RESULT

Tasks that are cancelled successfully in-progress should return this cancelled result, so that the task status can be updated accordingly.

See Also:

Constant Field Values

Constructor Detail

AsyncTask

protected AsyncTask()

Set up the AsyncTask in ready-to-run mode.

Method Detail

getStatus

public final int getStatus()

Fetches the current status of the task.

Returns:

the current status of the task

isFinished

public boolean isFinished()

Fetch whether this task is completed or not. Returns true if this task was completed (sucessful or failed with exception) or cancelled, or false if the task is still running or has not been started yet.

Returns:

true if the task is finished or cancelled, false otherwise

waitUntilFinished

public void waitUntilFinished()

Waits until the task is finished (i.e., isFinished() returns true). This will block the current thread.

waitUntilFinished

public void waitUntilFinished(int ms)

Waits until the task is finished (i.e., isFinished() returns true). This will block the current thread. Specifying a smaller sleep granularity will avoid waiting for extra unnecessary time, but may also cause more overhead (due to this thread waking up more often to check whether the task is finished.)

Parameters:

ms - the sleep granularity to use

sleep

protected static void sleep(int ms)

Utility routine to sleep for the given amount of time.

Parameters:

ms - the time in ms to sleep

run

public final void run()

Performs the task. This sets up the status of the task, and delegates to runImpl().

Specified by:

run in interface java.lang.Runnable

runImpl

protected abstract java.lang.Object runImpl()
                                     throws AsyncTask.CancelledException

Implementation of the task. Implementation-specific return results can be returned here, and will be stored in the task result. If the task is cancelled successfully in-progress, the implementation should return CANCELLED_RESULT here, or throw a CancelledException.

Returns:

the implementation-specific return result (if any), or CANCELLED_RESULT if the operation is cancelled

Throws:

AsyncTask.CancelledException - if the task has been cancelled

requestCancelImpl

protected abstract void requestCancelImpl()

Request to cancel the task in-progress, to be implemented by the implementation. If the task supports this, return CANCELLED_RESULT from runImpl().

isCancelledImpl

protected abstract boolean isCancelledImpl()

Return whether the task is marked for cancellation, to be implemented by the implementation.

Returns:

whether the task is marked for cancellation

requestCancel

protected final void requestCancel()

Request to cancel the task. The task will be cancelled if possible.

bailIfCancelled

protected void bailIfCancelled()
                        throws AsyncTask.CancelledException

Checks if the task has been marked for cancellation, and throws a CancelledException if it has. Implementations can call this routine from runImpl() as a way of bailing out of the task if a cancellation has occurred.

Throws:

AsyncTask.CancelledException - if the task has been marked for cancellation

getResult

public final java.lang.Object getResult()

Fetch the completed result of the task (if any).

Returns:

the task result