ewe.sys
Class AsyncTask

java.lang.Object
  ewe.sys.TaskObject
      ewe.sys.AsyncTask

All Implemented Interfaces:

Runnable, Task

public class AsyncTask

extends TaskObject

An AsyncTask is used to execute a single method in a target Object, or a static method in a class in a separate thread, returning a Handle that can be used to monitor and (in some cases) control the execution of the method.

This can be a convenient way of doing a background task without having to create a separate anonymous Thread or Task for that particular task, which would increase the size of your code.

This class is most useful for methods which take a Handle as a parameter and which use the provided Handle to determine if the execution of the method should abort. This gives another Thread the ability to abort the execution by calling the stop() method on the Handle. With methods like these the AsyncTask will automatically create a Handle, send it to the method in the background Thread and return it to the foreground Thread. The foreground thread can then stop the method by calling stop() on it if needed.

Note: the current implementation of AsyncTask is a TaskObject, which is itself has a Handle. So in fact creating the new thread involves the calling of doRun() on this AsyncTask which then passes its handle to the target Method and so the Handle returned by the various invoke() methods is the AsyncTasks handle. However future implementations may do this differently so you should not assume that the returned Handle is the same as the AsyncTask's Handle.

Note Also: When the method is complete and has returned the return value of the target method (if any) is placed in the returnValue field of the Handle and the Handle flags Success and Stopped will be set. The only time the Failed flag will be set is if the method returns a boolean type and it returns false, OR if the the stop() method is called on the Handle, OR if an exception is thrown (in which case the exception is placed in the error field of the Handle).

Field Summary

Fields inherited from class ewe.sys.TaskObject

handle, interruptThreadToStop, myThread, napIterations, napTime, shouldStop

Constructor Summary

AsyncTask()
Create a new AsyncTask.

AsyncTask(Class objectClass, String nameAndParametersAndType, boolean declaredOnly)
Create a new AsyncTask specifying the class of the target object and the full name and specs for the method.

AsyncTask(String objectClass, String nameAndParametersAndType)
Create a new AsyncTask specifying the class of the target object as a String and the full name and specs for the method.

Method Summary

protected void	doRun() Override this method if you want to use an mThread to run your Task.
Handle	invoke(Object target) Invoke the method on the target in a separate Thread and return a Handle to the task.
Handle	invoke(Object target, Object[] parameters) Invoke the method on the target in a separate Thread and return a Handle to the task.
Handle	invoke(Object target, Object[] parameters, int handleIndex) Invoke the method on the target in a separate Thread and return a Handle to the task.
Handle	invoke(Object targetOrClass, String nameAndParametersAndType) This method combines a call to setMethod() followed by a call to invoke().
Handle	invoke(Object targetOrClass, String nameAndParametersAndType, Object[] parameters) This method combines a call to setMethod() followed by a call to invoke().
Handle	invoke(Object targetOrClass, String nameAndParametersAndType, Object[] parameters, int handleIndex) This method combines a call to setMethod() followed by a call to invoke().
AsyncTask	setMethod(Class objectClass, String nameAndParametersAndType, boolean declaredOnly) Set the method given the class of the target object and the full name and specs for the method.
AsyncTask	setMethod(Method execMethod) Set the Method to be executed by the AsyncTask.

Methods inherited from class ewe.sys.TaskObject

checkAbortFail, checkFailure, doStart, doStop, exec, getHandle, nap, run, setNapTime, show, sleep, start, startTask, stopTask, waitOn, waitOnAny, waitOnSuccess, yield, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Constructor Detail

AsyncTask

public AsyncTask()

Create a new AsyncTask. After calling this you must call the setMethod() method followed by an invoke() method.

AsyncTask

public AsyncTask(Class objectClass,
                 String nameAndParametersAndType,
                 boolean declaredOnly)

Create a new AsyncTask specifying the class of the target object and the full name and specs for the method.

Parameters:

objectClass - the Class of the target object.

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

declaredOnly - true to search only for methods actually declared by the class and not by any superclasses.

AsyncTask

public AsyncTask(String objectClass,
                 String nameAndParametersAndType)

Create a new AsyncTask specifying the class of the target object as a String and the full name and specs for the method.

Parameters:

objectClass - the normal dot encoded Java name of the class (e.g. "java.lang.Object").

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

Method Detail

setMethod

public AsyncTask setMethod(Method execMethod)

Set the Method to be executed by the AsyncTask.

Parameters:

execMethod - the Method to be executed by the AsyncTask.

Returns:

this AsyncTask.

setMethod

public AsyncTask setMethod(Class objectClass,
                           String nameAndParametersAndType,
                           boolean declaredOnly)

Set the method given the class of the target object and the full name and specs for the method.

Parameters:

objectClass - the Class of the target object.

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

declaredOnly - true to search only for methods actually declared by the class and not by any superclasses.

Returns:

this AsyncTask.

invoke

public Handle invoke(Object target,
                     Object[] parameters,
                     int handleIndex)

Invoke the method on the target in a separate Thread and return a Handle to the task.

Parameters:

target - the target object.

parameters - the parameters to be sent to the method. Leave the parameter which is supposed to be a provided Handle as null and a new Handle will be created and provided.

handleIndex - the index of the Handle parameter. This AsyncTask will be sent as the Handle parameter. If handleIndex is -1 then no Handle is sent. If you want the handleIndex to be determined automatically use the invoke(Object target, Object[] parameters) method instead.

Returns:

a Handle to the task which is executing the Method.

invoke

public Handle invoke(Object target,
                     Object[] parameters)

Invoke the method on the target in a separate Thread and return a Handle to the task. The AsyncTask will automatically determine which is the correct index for the Handle to be provided (if any).

Parameters:

target - the target object.

parameters - the parameters to be sent to the method. Leave the parameter which is supposed to be a provided Handle as null and a new Handle will be created and provided.

Returns:

a Handle to the task which is executing the Method.

invoke

public Handle invoke(Object target)

Invoke the method on the target in a separate Thread and return a Handle to the task. The AsyncTask will automatically determine which is the correct index for the Handle to be provided (if any). This method can be used if the method takes no parameters OR if the method takes only one parameter which is a Handle. In this case, the Handle will provided.

Parameters:

target - the target object.

Returns:

a Handle to the task which is executing the Method.

invoke

public Handle invoke(Object targetOrClass,
                     String nameAndParametersAndType)

This method combines a call to setMethod() followed by a call to invoke().

Parameters:

targetOrClass - The target object or a Class object if the target method is static. This method can be used if the method takes no parameters OR if the method takes only one parameter which is a Handle. In this case, the Handle will provided.

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

Returns:

a Handle to the task which is executing the Method.

invoke

public Handle invoke(Object targetOrClass,
                     String nameAndParametersAndType,
                     Object[] parameters,
                     int handleIndex)

This method combines a call to setMethod() followed by a call to invoke().

Parameters:

targetOrClass - The target object or a Class object if the target method is static.

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

parameters - the parameters to be sent to the method. Leave the parameter which is supposed to be a provided Handle as null and a new Handle will be created and provided.

handleIndex - the index of the Handle parameter. This AsyncTask will be sent as the Handle parameter. If handleIndex is -1 then no Handle is sent. If you want the handleIndex to be determined automatically use the method that does not have a handleIndex parameter.

Returns:

a Handle to the task which is executing the Method.

invoke

public Handle invoke(Object targetOrClass,
                     String nameAndParametersAndType,
                     Object[] parameters)

This method combines a call to setMethod() followed by a call to invoke().

Parameters:

targetOrClass - The target object or a Class object if the target method is static.

nameAndParametersAndType - the fully encoded name and type of the method: e.g. invokeMethod(Ljava/lang/Class;Ljava/lang/Object;Ljava/lang/String;[Ljava/lang/Object;Z)Leve/sys/Wrapper;

parameters - the parameters to be sent to the method. Leave the parameter which is supposed to be a provided Handle as null and a new Handle will be created and provided.

Returns:

a Handle to the task which is executing the Method.

doRun

protected void doRun()

Description copied from class: TaskObject

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.

Overrides:

doRun in class TaskObject