public class Handle extends Object implements HasProperties
Modifier and Type | Class and Description |
---|---|
static interface |
Handle.ObjectDiscarder
This interface is used by an Object that knows how to discard of a particular
Object.
|
class |
Handle.WaitOnChange
This class allows you to monitor the state of the Handle without having to maintain the state
values yourself.
|
Modifier and Type | Field and Description |
---|---|
static int |
Aborted
A status flag indicating that the process has been aborted, probably through
user intervention.
|
static int |
Changed
Deprecated.
- don't use this flag to wait for a change. Instead, synchronize with the Handle, call getChangeState()
and then call waitOnChange().
|
static int |
DEFAULT_CHANGE_ACCEPT_TIME
This is the changeable default change accept time in milliseconds.
|
static float |
DEFAULT_PROGRESS_RESOLUTION
This is the changeable default progress resolution.
|
String |
doing
This is a human readable text version of what the process is currently doing.
|
Throwable |
error
If an error occurs an Exception should be created and placed here.
|
static int |
Failed
This is the Failure flag ORed with the Stopped flag.
|
static int |
Failure
A status flag indicating that the process has met with failure
|
static int |
OPTION_STOP_IF_NOT_SET
An option for waitOnFlags() - may also be used with or without OPTION_TIMEOUT_IF_NOT_SET
|
static int |
OPTION_TIMEOUT_IF_NOT_SET
An option for waitOnFlags() - may also be used with or without OPTION_TIMEOUT_IF_NOT_SET
|
float |
progress
This indicates the current progress of the running process.
|
float |
progressResolution
By default this is 0.
|
int |
returnCode
If the process returns an integer return value or code, it should be placed here.
|
Object |
returnValue
If the process is supposed to produce or return an object value, it should be
put here.
|
static int |
Running
A status flag indicating that the process is still running.
|
boolean |
shouldStop
This gets set to true if the stop() method is called.
|
long |
startTime
This is the time that the task started at.
|
protected int |
state
This is the state of the handle.
|
static int |
Stopped
A status flag indicating that the process has stopped.
|
int |
stopReason
This is the reason given to the stop() method.
|
Handle |
subHandle
This is a Handle that is considered to be a lower level of the current Handle.
|
static int |
Succeeded
This is the Success flag ORed with the Stopped flag.
|
static int |
Success
A status flag indicating that the process has met with success.
|
int |
waitChangeAcceptedTime
If this is greater than zero, then checkChangeAccepted() is called whenever
changed() is called.
|
Constructor and Description |
---|
Handle()
Tell the Handle that current or future returnValues should be discarded.
|
Handle(int status,
Object returnValue)
Create a completed Handle that has its state set to the specified value ORed with Stopped
and has its returnValue field set to the provided parameter.
|
Handle(Throwable t)
Create a failed Handle that has its state set to Failed and has its error
field set to the provided parameter.
|
Modifier and Type | Method and Description |
---|---|
void |
addParent(Handle h) |
void |
changeAccepted()
Signal to the Handle that a change has been accepted.
|
int |
changed()
Signal that the state has changed somehow (e.g. like the progress
or doing field) even if the state bits have not.
|
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 |
checkAbortFail(Handle wasWaitingOn,
boolean stopWaitingOn)
This can be used after a call to waitOn() or waitOnAny() has failed.
|
boolean |
checkAny(int flags)
Checks to see if any of the specified flags have been set.
|
int |
checkChangeAccepted(int valueFromChanged,
int timeout)
This is similar to the waitChangeAcceptedMethod() except that:
If the timeout is zero no waiting is done at all and zero is returned.
|
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.
|
Throwable |
convertError(Class exceptionClass,
String defaultMessage)
Convert the error of this Handle to an Exception of the specified class if it is
not already so or even if it is null.
|
protected int |
doChangeTo(int newstate,
boolean noChangeNotify) |
boolean |
fail(Throwable t)
Set the Stopped and Failure bits of this Handle and set the errorObject
to be the specified Throwable.
|
int |
getChangeState() |
String |
getErrorText(String defaultText) |
Object |
getFinalReturnValue()
Call this either after the handle has stopped to get the final return value, or if the process must be aborted.
|
PropertyList |
getProperties()
Get the PropertyList object associated with this object.
|
Object |
getReturnValue(TimeOut waitTime,
boolean stopOnTimeout)
Call this in the case where the process returns an Object on success.
|
Handle |
getStoppableWaitOnSuccess()
If this Handle cannot be stopped (i.e. although the handle can be used to monitor
a task, it cannot be used to stop it) then calling this method will return a Handle
that monitors this Handle and that handle can be aborted via stop().
|
Object |
getUnwrappedReturnValue()
Only call this if you expect the returnValue to be set to some meaningful value on completion.
|
boolean |
hasStopped() |
protected void |
interrupt() |
Handle.WaitOnChange |
newWaitOnChange()
Return a new WaitOnChange object for this Handle, which should be used by a single Thread only.
|
void |
removeParent(Handle h) |
void |
resetProgress(float progressResolution) |
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.
|
int |
setProgress(float currentProgress) |
int |
setProgress(float currentProgress,
String newDoing) |
boolean |
setResult(Object returnValue)
Set the returnValue of the Handle and then set the Stopped and Success bits - this
is the same as succeed().
|
boolean |
setReturnValue(Object ret)
This is identical to succeed(Object returnValue).
|
Handle |
start()
This tells the handle to ask its associated task to start.
|
int |
startDoing(String doing)
This method does the following:
It sets the doing field to the specified parameter.
|
void |
stop(int reason)
This tells the handle to ask its associated task to stop.
|
boolean |
succeed(Object returnValue)
Set the returnValue of the Handle and then set the Stopped and Success bits - this
is the same as setResult().
|
boolean |
succeeded() |
void |
throwErrorIfNotStopped() |
void |
throwRuntimeError()
If the error for this Handle is an Error or a RuntimeException, then this method
will throw it, otherwise it will throw a new RuntimeException with the message "Unknown error."
|
void |
throwRuntimeError(Error defaultException)
If the error for this Handle is an Error or a RuntimeException, then this method
will throw it, otherwise it will throw defaultException.
|
void |
throwRuntimeError(RuntimeException defaultException)
If the error for this Handle is an Error or a RuntimeException, then this method
will throw it, otherwise it will throw defaultException.
|
void |
throwRuntimeError(String defaultMessage)
If the error for this Handle is an Error or a RuntimeException, then this method
will throw it, otherwise it will throw a new RuntimeException with the defaultMessage.
|
boolean |
timeout()
This calls stop() and sets the status of the handle to Failed and sets error to be a TimedOutException
assuming that the Handle has not already stopped.
|
boolean |
timeout(String timeoutMessage)
This calls stop() and sets the status of the handle to Failed and sets error to be a TimedOutException
assuming that the Handle has not already stopped.
|
boolean |
waitChangeAccepted(int valueFromChanged,
int timeout)
Wait until the changeAcceptedMethod() was called.
|
Object |
waitForReturnValue()
This method waits until the Handle has stopped, ignoring any interrupts
and then returns the returnValue field.
|
boolean |
waitOn(Handle otherHandle,
int flags,
TimeOut t,
boolean copyProgress)
Wait until the flags of another Handle have been set to a particular value.
|
void |
waitOn(int flags)
This causes the current Thread 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 Thread 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 Thread 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 |
waitOnAny(Handle otherHandle,
int flags,
TimeOut t,
boolean copyProgress)
Wait until at least one bit in the flags of another Handle have been set to a particular value.
|
void |
waitOnAny(int flags)
This causes the current Thread 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 Thread 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 Thread 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 |
waitOnChange(int changeState,
TimeOut howLong) |
Object |
waitOnResult(TimeOut waitFor)
This calls waitOnSuccess(waitFor) and then returns the returnValue if it returned
true, or null if it returned false.
|
boolean |
waitOnSuccess(Handle otherHandle,
TimeOut t,
boolean copyProgress)
Wait until the otherHandle has the Success flag set.
|
boolean |
waitOnSuccess(TimeOut waitFor)
Wait for a specific length of time for a returnValue to be set and the handle state to
be set to Succeess via the setResult() or succeed() calls - but stop() the Handle if
the result is not available during the timeout period.
|
Object |
waitReturnValue()
Wait indefinitely, ignoring InterruptedExceptions, for the process to succeed
and return a value.
|
void |
waitUntilCompletion()
Wait until the Handle has stopped, but do not allow the thread to be interrupted.
|
boolean |
waitUntilCompletion(TimeOut howLong)
Wait until the Handle has stopped, but do not allow the thread to be interrupted.
|
void |
waitUntilStopped()
Wait until the Handle has stopped.
|
boolean |
waitUntilStopped(TimeOut howLong)
Wait until the Handle has stopped.
|
boolean |
wasAborted()
Return if the Aborted bit was set OR the error is an AbortedException.
|
void |
yield() |
public static float DEFAULT_PROGRESS_RESOLUTION
public static int DEFAULT_CHANGE_ACCEPT_TIME
public int returnCode
public Object returnValue
public static final int Changed
public static final int Stopped
public static final int Success
public static final int Failure
public static final int Running
public static final int Aborted
public static final int OPTION_TIMEOUT_IF_NOT_SET
public static final int OPTION_STOP_IF_NOT_SET
public static final int Succeeded
public static final int Failed
public float progress
Use setProgress() to update this variable and notify waiters on the change.
public float progressResolution
public Throwable error
public long startTime
public boolean shouldStop
public int stopReason
public String doing
protected int state
public Handle subHandle
public int waitChangeAcceptedTime
public Handle()
public Handle(int status, Object returnValue)
public Handle(Throwable t)
public void addParent(Handle h)
public void removeParent(Handle h)
protected void interrupt()
public PropertyList getProperties()
HasProperties
getProperties
in interface HasProperties
public boolean fail(Throwable t)
public boolean succeed(Object returnValue)
public boolean setResult(Object returnValue)
public boolean timeout(String timeoutMessage)
timeoutMessage
- a message for the TimedOutException().public boolean timeout()
public boolean waitOnSuccess(TimeOut waitFor)
waitFor
- the length of time to wait for.public Object waitOnResult(TimeOut waitFor)
waitFor
- the length of time to wait for.public void resetProgress(float progressResolution)
public int setProgress(float currentProgress, String newDoing)
public int setProgress(float currentProgress)
public int startDoing(String doing)
doing
- the new value for the doing field.maxProgress
- the value to set maxProgress to.public int getChangeState()
public boolean waitOnChange(int changeState, TimeOut howLong) throws HandleStoppedException, InterruptedException
public int changed()
public void changeAccepted()
public boolean waitChangeAccepted(int valueFromChanged, int timeout)
valueFromChanged
- the value returned from the changed(), setProgress()
or startDoing() method.timeout
- the length of time to wait.public int checkChangeAccepted(int valueFromChanged, int timeout)
If the timeout is zero no waiting is done at all and zero is returned. If the changeAccepted() method was not called within the timeout zero is returned. If the changeAccepted() method was called, the timeout is returned.This provides a simple way of initially waiting for the change to be accepted, but if it was not accepted within an acceptable time, no further waits will be done (in case there is nothing monitoring the handle).
To use it do something like this:
int waitTime = 100; // 1/10th of a second. Handle h = new Handle(); int v = h.startDoing("Beginning..."); waitTime = checkChangeAccepted(v,waitTime); for (int i = 0; i
valueFromChanged
- timeout
- protected final int doChangeTo(int newstate, boolean noChangeNotify)
public final void set(int newstate)
public final void setFlags(int switchOn, int switchOff)
switchOn
- Flag bits to switch on.switchOff
- Flag bits to swtich off.public void yield()
public final boolean hasStopped()
public final int check()
public final boolean waitOn(int flags, TimeOut t) throws HandleStoppedException, InterruptedException
flags
- The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.t
- The TimeOut to wait for.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final boolean waitOn(int flags, int t) throws HandleStoppedException, InterruptedException
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.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final void waitOn(int flags) throws HandleStoppedException, InterruptedException
flags
- The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final boolean waitOnAny(int flags, TimeOut t) throws HandleStoppedException, InterruptedException
flags
- The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.t
- The TimeOut to wait for.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final boolean waitOnAny(int flags, int t) throws HandleStoppedException, InterruptedException
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.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final void waitOnAny(int flags) throws HandleStoppedException, InterruptedException
flags
- The flag bits to wait for. Must NOT be zero; an IllegalArgumentException is thrown if it is.HandleStoppedException
- If the handle has the Stopped flag set before all the flags were set.InterruptedException
- If the Thread was interrupted.public final boolean waitUntilStopped(TimeOut howLong) throws InterruptedException
howLong
- How long to wait for.InterruptedException
- if the Thread was interrupted.public final void waitUntilStopped() throws InterruptedException
InterruptedException
- if the Thread was interrupted.public final boolean waitUntilCompletion(TimeOut howLong)
howLong
- How long to wait for.public final void waitUntilCompletion()
public final boolean check(int flags) throws HandleStoppedException
flags
- The flag bits to check for.HandleStoppedException
- If the handle has the Stopped flag set AND the handle does
not have the specified flag bits set.public final boolean checkAny(int flags) throws HandleStoppedException
flags
- The flag bits to check for.HandleStoppedException
- If the handle has the Stopped flag set AND the handle does
not have any of the specified flag bits set.public final boolean succeeded()
public void stop(int reason)
public Handle start()
public final boolean waitOn(Handle otherHandle, int flags, TimeOut t, boolean copyProgress)
otherHandle
- The other Handle to wait on.flags
- The flag bits to wait for.t
- The time to wait for.copyProgress
- if this is true then the progress of this Handle will be made the same
as the progress of otherHandle.public final boolean waitOnAny(Handle otherHandle, int flags, TimeOut t, boolean copyProgress)
otherHandle
- The other Handle to wait on.flags
- The flag bits to wait for.t
- The time to wait for.copyProgress
- if this is true then the progress of this Handle will be made the same
as the progress of otherHandle.public final boolean checkAbortFail(Handle wasWaitingOn, boolean stopWaitingOn)
Only call this from within the TaskObject's thread.
wasWaitingOn
- The Handle that this task was waiting on.stopWaitingOn
- If this is true then wasWaitingOn will have its stop() method called.public final boolean checkFailure(boolean resultOfWait, Handle wasWaitingOn, boolean stopWaitingOn)
Only call this from within the TaskObject's thread.
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.public final boolean waitOnSuccess(Handle otherHandle, TimeOut t, boolean copyProgress)
otherHandle
- the otherHandle to wait on.t
- The timeout period.copyProgress
- if this is true then the progress of this Handle will be made the same
as the progress of otherHandle.public Handle getStoppableWaitOnSuccess()
public Throwable convertError(Class exceptionClass, String defaultMessage)
exceptionClass
- The type of the exception return.defaultMessage
- If there is no current error, or no message associated with
the error, then this message will be used to create the new Exception.public void throwRuntimeError(RuntimeException defaultException)
defaultException
- the default exception to throw.
If this is null a RuntimeException will created and thrown.public void throwRuntimeError(Error defaultException)
defaultException
- the default exception to throw.
If this is null a RuntimeException will created and thrown.public void throwRuntimeError()
public void throwRuntimeError(String defaultMessage)
defaultMessage
- the default message to throw.
If this is null the message "Unknown error." will be thrown.public Object waitForReturnValue()
public Object getReturnValue(TimeOut waitTime, boolean stopOnTimeout) throws InterruptedException, HandleStoppedException
waitTime
- how long to wait. If this elapses without any return value
then null is returned.stopOnTimeout
- if this is true then timeout() will be called on the Handle
if the time expires but the process has not succeeded. This will call stop() on
the Handle to let it know to stop and not return any value.InterruptedException
- if the Thread was interrupted while waiting.HandleStoppedException
- if the process stops but did not succeed. Check
the error field to see if an error was thrown by the process or if.public Object getFinalReturnValue()
public Object waitReturnValue()
public boolean wasAborted()
public boolean setReturnValue(Object ret)
ret
- the Object to return.public Object getUnwrappedReturnValue()
public Handle.WaitOnChange newWaitOnChange()