ewe.sys
Class Handle

java.lang.Object
  ewe.sys.Handle

All Implemented Interfaces:

Task, TimerProc

Direct Known Subclasses:

IOHandle, RemoteCall

public class Handle

extends Object

implements TimerProc, Task

Field Summary

static int	Aborted
static int	Changed
String	doing This is a text version of what the process is currently doing.
String	error If the process stopped due to an error.
int	errorCode This is an application specific error code.
Object	errorObject This can be used for more detailed error handling.
static int	Failed
static int	Failure
protected int	nativeResult This is not to be written to! It is used when interfacing with native threads.
float	progress This gives an indication of the progress of the process.
float	progressResolution If this is set to 0 then a call to changed() is done everytime setProgress() is set, otherwise changed is called only when the progress has increased past the last setProgress() by this value.
Object	returnValue If the process is supposed to produce or return a value, it should be put here.
static int	Running
boolean	shouldStop This gets set to true if the stop() method is called, in addition to it calling the stop() method of the associated task.
long	startTime This is the time that the task started at.
protected int	state This is the state of the handle.
static int	Stopped
int	stopReason This is the reason given to the stop() method.
static int	Succeeded
static int	Success
Task	task This is the Task associated with the handle (if any).

Constructor Summary

Handle()

Handle(int status, Object returnValueOrErrorString)
Create a Handle that has its status preset.

Handle(Task p)

Handle(Throwable error)
Create a Handle that has its status preset to Failed.

Method Summary

HandleStatus	callBackOnAnyFlag(CallBack cb, int flags, TimeOut t)
HandleStatus	callBackOnFlags(CallBack cb, int flags, TimeOut t)
void	callWhenStopped(CallBack cb) This calls callWhenStopped() with a null timeout.
void	callWhenStopped(CallBack cb, TimeOut timeout) This causes a CallBack object to be called when the handle is reported as having stopped.
void	cancelCallBack(CallBack cb)
void	changed() This notifies any waiters that something about the handle may have changed.
int	check() This returns the state of the handle.
boolean	check(int flags) Checks to see if all the specified flags have been set.
boolean	checkAny(int flags) Checks to see if any of the specified flags have been set.
Handle	clearTag(int tag) Use this for passing custom data to and from the processes.
protected HandleStatus	doCallBackOnFlags(CallBack cb, int flags, TimeOut t, boolean doAll)
void	fail(Throwable t) Set the Stopped and Failure bits of this Handle and set the errorObject to be the specified Throwable.
void	failed(Object error) Mark the handle as failed and set the errorObject to be error.
String	getErrorText(String defaultText)
Handle	getHandle() Task implementation - This will return itself.
Handle	getSubHandle()
Handle	getSubHandle(String doing) Get a new Handle that will be stopped if this handle is stopped.
Object	getTag(int tag, Object defaultValue) Use this for passing custom data to and from the processes.
Task	getTask()
boolean	hasStopped() Returns whether the Stopped bit has been set.
void	resetProgress(float progressResolution)
void	resetTime(String doing) This method does the following: It sets the doing field to the specified parameter.
void	set(int newstate) Everytime it is called it will ensure that any waiting Coroutines get notified so they can check to see if the state they are waiting for has been achieved.
void	setFlags(int switchOn, int switchOff) This sets and clears specific flags (bits) in the handle state.
void	setProgress(float progress)
Handle	setTag(int tag, Object value) Use this for passing custom data to and from the processes.
void	start() This tells the handle to ask its associated task to start.
Handle	startDoing(String doing) A convenience method that calls resetTime(doing) and then returns itself.
Handle	startTask() Task implementation - this will set the state of the handle to Running.
void	stop(int reason) This tells the handle to ask its associated task to stop.
void	stopAlsoIfStopped(Handle otherHandle) If the stop() method of this handle is called it will call stop() on the other handle.
Handle	stopTask(int reason) Task implementation - this will do nothing!
void	ticked(int id, int elapsed)
void	waitOn(int flags) This causes the current mThread to wait indefinitely until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOn(int flags, int t) This causes the current mThread to wait until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOn(int flags, TimeOut t) This causes the current mThread to wait until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOn(int flags, TimeOut checkTimeOut, Handle masterHandle, TimeOut masterTimeOut) This is used by one task to check on the progress of another.
void	waitOnAny(int flags) This causes the current mThread to wait indefinitely until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOnAny(int flags, int t) This causes the current mThread to wait until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter set, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOnAny(int flags, TimeOut t) This causes the current mThread to wait until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter set, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).
boolean	waitOnAny(int flags, TimeOut checkTimeOut, Handle masterHandle, TimeOut masterTimeOut) This is used by one task to check on the progress of another.
int	waitOnAnyFlag(int flags, TimeOut t) Deprecated. - use waitOnAny(int flags,TimeOut t) instead.
boolean	waitOnFlags(int flags, TimeOut t) Deprecated. - use waitOn(int flags,TimeOut t) instead.
boolean	waitOnFlags(int flags, TimeOut checkTimeOut, Handle masterHandle, TimeOut masterTimeOut) Deprecated. - use waitOn(int flags,TimeOut checkTimeOut,Handle masterHandle,TimeOut masterTimeOut) instead.
void	waitUntilStopped() Wait until the Handle has stopped.
boolean	waitUntilStopped(TimeOut howLong) Wait until the Handle has stopped.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

nativeResult

protected int nativeResult

This is not to be written to! It is used when interfacing with native threads.

returnValue

public Object returnValue

If the process is supposed to produce or return a value, it should be put here.

progress

public float progress

This gives an indication of the progress of the process. It should be in the range 0.0 to 1.0 (1.0 meaning complete).

Changed

public static final int Changed

See Also:

Constant Field Values

Stopped

public static final int Stopped

See Also:

Constant Field Values

Success

public static final int Success

See Also:

Constant Field Values

Failure

public static final int Failure

See Also:

Constant Field Values

Running

public static final int Running

See Also:

Constant Field Values

Aborted

public static final int Aborted

See Also:

Constant Field Values

Succeeded

public static final int Succeeded

See Also:

Constant Field Values

Failed

public static final int Failed

See Also:

Constant Field Values

task

public Task task

This is the Task associated with the handle (if any).

state

protected int state

This is the state of the handle.

doing

public String doing

This is a text version of what the process is currently doing.

errorCode

public int errorCode

This is an application specific error code.

error

public String error

If the process stopped due to an error. A description of the error should go here. Optional.

errorObject

public Object errorObject

This can be used for more detailed error handling.

startTime

public long startTime

This is the time that the task started at. Calling resetTime() will set it to be the current time and will set the progress to 0.0

shouldStop

public boolean shouldStop

This gets set to true if the stop() method is called, in addition to it calling the stop() method of the associated task.

stopReason

public int stopReason

This is the reason given to the stop() method.

progressResolution

public float progressResolution

If this is set to 0 then a call to changed() is done everytime setProgress() is set, otherwise changed is called only when the progress has increased past the last setProgress() by this value.

Constructor Detail

Handle

public Handle(int status,
              Object returnValueOrErrorString)

Create a Handle that has its status preset. If status has the Failure flag set and returnValueOrErrorString is a String, then the "error" variable is set to this value. Otherwise it sets returnValue to be the parameter.

Handle

public Handle(Throwable error)

Create a Handle that has its status preset to Failed.

Parameters:

error - An error

Handle

public Handle()

Handle

public Handle(Task p)

Method Detail

getTask

public final Task getTask()

getSubHandle

public Handle getSubHandle(String doing)

Get a new Handle that will be stopped if this handle is stopped.

getSubHandle

public Handle getSubHandle()

fail

public void fail(Throwable t)

Set the Stopped and Failure bits of this Handle and set the errorObject to be the specified Throwable.

changed

public final void changed()

This notifies any waiters that something about the handle may have changed. It causes a yield() on the current mThread.

set

public final void set(int newstate)

Everytime it is called it will ensure that any waiting Coroutines get notified so they can check to see if the state they are waiting for has been achieved.

setFlags

public final void setFlags(int switchOn,
                           int switchOff)

This sets and clears specific flags (bits) in the handle state. Everytime it is called it will ensure that any waiting Coroutines get notified so they can check to see if the state they are waiting for has been achieved.

Parameters:

switchOn - Flag bits to switch on.

switchOff - Flag bits to swtich off.

ticked

public void ticked(int id,
                   int elapsed)

Specified by:

ticked in interface TimerProc

check

public final int check()

This returns the state of the handle.

waitOn

public final boolean waitOn(int flags,
                            TimeOut t)
                     throws HandleStoppedException,
                            InterruptedException

This causes the current mThread to wait until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

t - The TimeOut to wait for.

Returns:

true if the flags were all set within the timeout period, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitOn

public final boolean waitOn(int flags,
                            int t)
                     throws HandleStoppedException,
                            InterruptedException

This causes the current mThread to wait until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

t - The time in milliseconds to wait.

Returns:

true if the flags were all set within the timeout period, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitOn

public final void waitOn(int flags)
                  throws HandleStoppedException,
                         InterruptedException

This causes the current mThread to wait indefinitely until the status of the Handle has ALL the flag bits set as specified by the "flags" parameter, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitOnAny

public final boolean waitOnAny(int flags,
                               TimeOut t)
                        throws HandleStoppedException,
                               InterruptedException

This causes the current mThread to wait until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter set, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

t - The TimeOut to wait for.

Returns:

true if any of the flags were all set within the timeout period, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitOnAny

public final boolean waitOnAny(int flags,
                               int t)
                        throws HandleStoppedException,
                               InterruptedException

This causes the current mThread to wait until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter set, or until the Timout specified expires, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

t - The time in milliseconds to wait.

Returns:

true if any of the flags were all set within the timeout period, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitOnAny

public final void waitOnAny(int flags)
                     throws HandleStoppedException,
                            InterruptedException

This causes the current mThread to wait indefinitely until the status of the Handle has at least one of the flag bits set as specified by the "flags" parameter, or until the Handle has the Stopped bit set (in which case an Exception is thrown).

Parameters:

flags - The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.

Throws:

HandleStoppedException - If the handle has the Stopped flag set before all the flags were set.

InterruptedException - If the Thread was interrupted.

waitUntilStopped

public final boolean waitUntilStopped(TimeOut howLong)
                               throws InterruptedException

Wait until the Handle has stopped.

Parameters:

howLong - How long to wait for.

Returns:

true if the Handle stopped within the TimeOut period, false if not.

Throws:

InterruptedException - if the Thread was interrupted.

waitUntilStopped

public final void waitUntilStopped()
                            throws InterruptedException

Wait until the Handle has stopped.

Throws:

InterruptedException - if the Thread was interrupted.

check

public final boolean check(int flags)
                    throws HandleStoppedException

Checks to see if all the specified flags have been set.

Parameters:

flags - The flag bits to check for.

Returns:

true if the bits are all set, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set AND the handle does not have the specified flag bits set.

checkAny

public final boolean checkAny(int flags)
                       throws HandleStoppedException

Checks to see if any of the specified flags have been set.

Parameters:

flags - The flag bits to check for.

Returns:

true if any of the bits are set, false if not.

Throws:

HandleStoppedException - If the handle has the Stopped flag set AND the handle does not have any of the specified flag bits set.

waitOnFlags

public final boolean waitOnFlags(int flags,
                                 TimeOut t)

Deprecated. - use waitOn(int flags,TimeOut t) instead.

waitOnAnyFlag

public final int waitOnAnyFlag(int flags,
                               TimeOut t)

Deprecated. - use waitOnAny(int flags,TimeOut t) instead.

doCallBackOnFlags

protected final HandleStatus doCallBackOnFlags(CallBack cb,
                                               int flags,
                                               TimeOut t,
                                               boolean doAll)

callBackOnFlags

public final HandleStatus callBackOnFlags(CallBack cb,
                                          int flags,
                                          TimeOut t)

callBackOnAnyFlag

public final HandleStatus callBackOnAnyFlag(CallBack cb,
                                            int flags,
                                            TimeOut t)

cancelCallBack

public final void cancelCallBack(CallBack cb)

stop

public void stop(int reason)

This tells the handle to ask its associated task to stop. It does not guarantee to immediately stop the task. The task, because it may be an asynchronous task, will do so on its own time.

start

public void start()

This tells the handle to ask its associated task to start. It does not guarantee to immediately start the task. The task, because it may be an asynchronous task, will do so on its own time.

getHandle

public Handle getHandle()

Task implementation - This will return itself.

Specified by:

getHandle in interface Task

startTask

public Handle startTask()

Task implementation - this will set the state of the handle to Running.

Specified by:

startTask in interface Task

stopTask

public Handle stopTask(int reason)

Task implementation - this will do nothing!

Specified by:

stopTask in interface Task

callWhenStopped

public void callWhenStopped(CallBack cb,
                            TimeOut timeout)

This causes a CallBack object to be called when the handle is reported as having stopped. If a non-null timeout is provided then it will only wait for that length of time.

Parameters:

cb - the CallBack object to be called when the handle has stopped. The callBack() method will be called with this handle as the parameter. However if the timeout expired before this handle stopped, then the parameter to the callBack() method will be null. Note that the callBack() method is called within a Coroutine.

timeout - An optional time to wait. If this is null it will wait forever.

callWhenStopped

public void callWhenStopped(CallBack cb)

This calls callWhenStopped() with a null timeout.

hasStopped

public boolean hasStopped()

Returns whether the Stopped bit has been set.

waitOnFlags

public boolean waitOnFlags(int flags,
                           TimeOut checkTimeOut,
                           Handle masterHandle,
                           TimeOut masterTimeOut)

Deprecated. - use waitOn(int flags,TimeOut checkTimeOut,Handle masterHandle,TimeOut masterTimeOut) instead.

waitOn

public boolean waitOn(int flags,
                      TimeOut checkTimeOut,
                      Handle masterHandle,
                      TimeOut masterTimeOut)
               throws HandleStoppedException,
                      InterruptedException

This is used by one task to check on the progress of another. It is best explained via the source code:

public boolean waitOn(int flags,TimeOut checkTimeOut,Handle masterHandle,TimeOut masterTimeOut) throws HandleStoppedException
{
        while(true){
                if (masterTimeOut.hasExpired() || masterHandle.shouldStop) return false;
                if (waitOn(flags,checkTimeOut.reset())) return true;
        }
}
 

Parameters:

flags - The bits to check for.

checkTimeOut - How long to check this Handle for each iteration.

masterHandle - The master handle controlling the operation.

masterTimeOut - The length of time the masterHandle is waiting for.

Returns:

true if all the flags were set within the masterTimeOut period, false if the masterTiimeOut expired or if the shouldStop flag of the masterHandle is set.

Throws:

HandleStoppedException - if this handle has its Stopped bits set.

InterruptedException - If the Thread was interrupted.

waitOnAny

public boolean waitOnAny(int flags,
                         TimeOut checkTimeOut,
                         Handle masterHandle,
                         TimeOut masterTimeOut)
                  throws HandleStoppedException,
                         InterruptedException

This is used by one task to check on the progress of another. It is best explained via the source code:

public boolean waitOnAny(int flags,TimeOut checkTimeOut,Handle masterHandle,TimeOut masterTimeOut) throws HandleStoppedException
{
        while(true){
                if (masterTimeOut.hasExpired() || masterHandle.shouldStop) return false;
                if (waitOnAny(flags,checkTimeOut.reset())) return true;
        }
}
 

Parameters:

flags - The bits to check for.

checkTimeOut - How long to check this Handle for each iteration.

masterHandle - The master handle controlling the operation.

masterTimeOut - The length of time the masterHandle is waiting for.

Returns:

true if any of the flags were set within the masterTimeOut period, false if the masterTiimeOut expired or if the shouldStop flag of the masterHandle is set.

Throws:

HandleStoppedException - if this handle has its Stopped bits set.

InterruptedException - If the Thread was interrupted.

resetProgress

public void resetProgress(float progressResolution)

setProgress

public void setProgress(float progress)

failed

public void failed(Object error)

Mark the handle as failed and set the errorObject to be error.

getErrorText

public String getErrorText(String defaultText)

resetTime

public void resetTime(String doing)

This method does the following:

1. It sets the doing field to the specified parameter.
2. It sets the startTime to the current time.
3. It sets the progress to 0.0
4. It calls changed() on the handle.

Parameters:

doing - the new value for the doing field.

startDoing

public Handle startDoing(String doing)

A convenience method that calls resetTime(doing) and then returns itself.

Parameters:

doing - The current task.

Returns:

itself.

setTag

public Handle setTag(int tag,
                     Object value)

Use this for passing custom data to and from the processes.

Parameters:

tag - a custom integer tag.

value - a value to pass.

Returns:

this Handle.

getTag

public Object getTag(int tag,
                     Object defaultValue)

Use this for passing custom data to and from the processes.

Parameters:

tag - a custom integer tag.

defaultValue - the default value.

Returns:

the Object associated with the tag or the defaultValue if the tag is not set.

stopAlsoIfStopped

public void stopAlsoIfStopped(Handle otherHandle)

If the stop() method of this handle is called it will call stop() on the other handle.

clearTag

public Handle clearTag(int tag)

Use this for passing custom data to and from the processes.

Parameters:

tag - a custom integer tag to clear.

Returns:

this Handle.