ewe.sys
Class TaskObject

java.lang.Object
  ewe.sys.TaskObject

All Implemented Interfaces:

Runnable, Task

Direct Known Subclasses:

AsyncTask, ClientServerConnector, CopyOver, EventDispatcher, ImageMover, IOTransfer, ThreadPool

public class TaskObject

extends Object

implements Task, Runnable

A TaskObject is an implementation of a Task that uses an mThread to run asynchronously.

To override a TaskObject you need only override the doRun() method. Within that method you can use the "handle" variable to modify the handle associated with the task. This handle will automatically be set to "Running" before doRun() is called and will be set to "Stopped" when doRun() exits.

Field Summary

protected Handle	handle This is the handle used by the TaskObject.
protected boolean	interruptThreadToStop If this is true, then a call to stopTask() will request the running thread to be interrupted.
protected mThread	myThread This is the thread in which the task is running.
int	napIterations Everytime the nap() method is called it calls Coroutine.nap(napIterations,napTime).
int	napTime Everytime the nap() method is called it calls Coroutine.nap(napIterations,napTime).
boolean	shouldStop This will be set true if the stop() method is called.

Constructor Summary

protected	TaskObject() Create a new TaskObject and assign a new Handle to the handle member.
protected	TaskObject(Handle h) Create a new TaskObject using a particular Handle.

Method Summary

boolean	checkAbortFail(Handle wasWaitingOn, boolean stopWaitingOn) This can be used after a call to waitOn() or waitOnAny() has failed.
boolean	checkFailure(boolean resultOfWait, Handle wasWaitingOn, boolean stopWaitingOn) Call this to check on the result of a waitOn() or waitOnAny() and automatically set the Failure or Abort flag of the handle of this task, based on the failure/success of waitOn.
protected void	doRun() Override this method if you want to use an mThread to run your Task.
protected void	doStart() This is called to start the TaskObject running.
protected void	doStop(int reason) This method, by default, sets the shouldStop variable to true.
Handle	exec(String title, Frame parent) This starts the task and displays a progress bar.
Handle	getHandle() Get the Handle for the TaskObject.
protected void	nap() Nap for the nap time of this task object.
void	run() This calls the doRun() method and then sets the handle flags such that Running is off and Stopped is on after doRun() returns.
TaskObject	setNapTime(int napIterations, int napTime) Set the napIterations and napTime variables.
Handle	show(String title, Frame parent) This starts the task and displays a progress bar.
protected static void	sleep(int time) This puts the current mThread thread to sleep.
ProgressBarForm	start(String title)
Handle	startTask() This sets the handle member to the Running state and then calls doStart().
Handle	stopTask(int reason) Request that the TaskObject stop running.
boolean	waitOn(Handle otherHandle, int flags, boolean copyProgress) Wait indefinitely for flags to be set on another handle.
boolean	waitOnAny(Handle otherHandle, int flags, boolean copyProgress) Wait indefinitely for any of a set of flags to be set on another handle.
boolean	waitOnSuccess(Handle waitFor, boolean copyProgress) This calls waitOn(waitFor,Handle.Success,copyProgress) and then calls checkFailure() on it.
void	yield() Yield to another thread or task.
void	yield(int everyMilliseconds) Yield to another thread or task every certain number of milliseconds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

handle

protected Handle handle

This is the handle used by the TaskObject.

shouldStop

public boolean shouldStop

This will be set true if the stop() method is called.

interruptThreadToStop

protected boolean interruptThreadToStop

If this is true, then a call to stopTask() will request the running thread to be interrupted.

myThread

protected mThread myThread

This is the thread in which the task is running.

napIterations

public int napIterations

Everytime the nap() method is called it calls Coroutine.nap(napIterations,napTime).

napTime

public int napTime

Everytime the nap() method is called it calls Coroutine.nap(napIterations,napTime).

Constructor Detail

TaskObject

protected TaskObject()

Create a new TaskObject and assign a new Handle to the handle member.

TaskObject

protected TaskObject(Handle h)

Create a new TaskObject using a particular Handle.

Method Detail

startTask

public Handle startTask()

This sets the handle member to the Running state and then calls doStart().

Specified by:

startTask in interface Task

Returns:

a Handle that can be used to monitor the state of the Task.

stopTask

public Handle stopTask(int reason)

Request that the TaskObject stop running.

Specified by:

stopTask in interface Task

Parameters:

reason - some task specific reason for stopping. There are no pre-defined reasons.

Returns:

the Handle for the TaskObject.

getHandle

public Handle getHandle()

Get the Handle for the TaskObject.

Specified by:

getHandle in interface Task

Returns:

the Handle for the TaskObject.

doStart

protected void doStart()

This is called to start the TaskObject running. By default it creates an mThread which then calls the run() method, which in turn calls the doRun() method. If you want to use an mThread to execute this Task then do not override this method, instead override the doRun() method.

If you want to use a different method for Task execution (e.g. Timer ticks or Callbacks) then override this method to start the task running.

doStop

protected void doStop(int reason)

This method, by default, sets the shouldStop variable to true. The Task should therefore always check this variable when coming out of a sleep() to see whether it should continue or stop.

You can override this to provide a different method of stopping the task.

Parameters:

reason - some task specific reason for stopping. There are no pre-defined reasons.

run

public final void run()

This calls the doRun() method and then sets the handle flags such that Running is off and Stopped is on after doRun() returns. You should therefore override doRun() instead of run().

Specified by:

run in interface Runnable

doRun

protected void doRun()

Override this method if you want to use an mThread to run your Task. Otherwise if you are using timers or callbacks, override the doStart() method.

sleep

protected static final void sleep(int time)

This puts the current mThread thread to sleep.

setNapTime

public TaskObject setNapTime(int napIterations,
                             int napTime)

Set the napIterations and napTime variables. Everytime the nap() method is called it calls Coroutine.nap(napIterations,napTime).

Parameters:

napIterations -

napTime -

Returns:

This TaskObject.

nap

protected void nap()

Nap for the nap time of this task object.

start

public ProgressBarForm start(String title)

exec

public Handle exec(String title,
                   Frame parent)

This starts the task and displays a progress bar.

show

public Handle show(String title,
                   Frame parent)

This starts the task and displays a progress bar.

waitOn

public boolean waitOn(Handle otherHandle,
                      int flags,
                      boolean copyProgress)

Wait indefinitely for flags to be set on another handle. If stopTask() is called on the task, or stop() is called on the handle of the task, then the wait will be interrupted and false will be returned. If the otherHandle stops before the flags are set then false will also be returned.

Only call this from within the TaskObject's thread.

Parameters:

otherHandle - The other handle to wait for.

flags - The flags to wait to be set.

copyProgress - set this true if you want the progress of the otherHandle to be reflected in this handle.

Returns:

true if the flags were set, false if stopTask() or handle.stop() was called, or if the flags were not set. You should check handle.shouldStop to determine what to do next.

waitOnAny

public boolean waitOnAny(Handle otherHandle,
                         int flags,
                         boolean copyProgress)

Wait indefinitely for any of a set of flags to be set on another handle. If stopTask() is called on the task, or stop() is called on the handle of the task, then the wait will be interrupted and false will be returned. If the otherHandle stops before the flags are set then false will also be returned.

Only call this from within the TaskObject's thread.

Parameters:

otherHandle - The other handle to wait for.

flags - The flags to wait to be set.

copyProgress - set this true if you want the progress of the otherHandle to be reflected in this handle.

Returns:

true if the flags were set, false if stopTask() or handle.stop() was called, or if the flags were not set. You should check handle.shouldStop to determine what to do next.

checkAbortFail

public boolean checkAbortFail(Handle wasWaitingOn,
                              boolean stopWaitingOn)

This can be used after a call to waitOn() or waitOnAny() has failed. If the shouldStop variable OR if the wasWaitingOn handle has the Aborted flag set, then the handle for this task will be set to Aborted and true will be returned. Otherwise this task's handle will be set to Failure, and its errorObject set to the same error object as wasWaitingOn. If stopWaitingOn is true then the stop() metod will be called on wasWaitingOn.

Only call this from within the TaskObject's thread.

Parameters:

wasWaitingOn - The Handle that this task was waiting on.

stopWaitingOn - If this is true then wasWaitingOn will have its stop() method called.

Returns:

true if this task or the wasWaitingOn task was aborted, false if wasWaitingOn had failed.

checkFailure

public boolean checkFailure(boolean resultOfWait,
                            Handle wasWaitingOn,
                            boolean stopWaitingOn)

Call this to check on the result of a waitOn() or waitOnAny() and automatically set the Failure or Abort flag of the handle of this task, based on the failure/success of waitOn.

Only call this from within the TaskObject's thread.

Parameters:

resultOfWait - The result of the waitOn() or waitOnAny() call.

wasWaitingOn - The hande the task was waiting on.

stopWaitingOn - If this is true then the task will be stopped on failure.

Returns:

will always be resultOfWait.

waitOnSuccess

public boolean waitOnSuccess(Handle waitFor,
                             boolean copyProgress)

This calls waitOn(waitFor,Handle.Success,copyProgress) and then calls checkFailure() on it. This will basically wait until either the waitFor handle has the Success flag set or until it has stopped without that flag being set (which usually indicates failure) or until the task has the stop method called (by shouldStop being set true). In the case of failure this task's handle will be set to either Failure or Aborted depending on whether the stop() method was called on this task's handle or whether the waitFor handle failed or aborted.

Only call this from within the TaskObject's thread.

Parameters:

waitFor - The handle to wait for.

copyProgress - True if you want this task's handle to reflect the progress of the waitFor handle.

Returns:

true on success, false on failure.

yield

public void yield()

Yield to another thread or task.

yield

public void yield(int everyMilliseconds)

Yield to another thread or task every certain number of milliseconds.