|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.ibm.datapower.wamt.clientAPI.ProgressContainer
public class ProgressContainer
A ProgressContainer is the vehicle that the manager uses to inform the caller
(likely a user presentation) of the progress on a long-running method. Think
of this as a rendezvous object. Methods are long-running probably because a
device has to be communicated with via AMP. The caller will get notified via
this object that there was an update in the progression and can read the new
progress point from this object. The caller should block using
waitForUpdate()
, and then retrieve the new data via the gettr
methods. Alternatively the caller could poll via hasUpdate
, and
then when it returns true call the gettr methods. Or if you do not need to be
informed of interim progress, you could use the method waitForEnd()
.
If there is any return value from the long-running method, it will be
available for retrieval from this object. Similarly, if there is any
Exception from the long-running method, it will be available for retrieval
from this object.
Typical usage looks like this:
ProgressContainer progressContainer = longRunningCommandInvocation(); // the invocation returns quickly but the long-running work is performed on another thread while (!progressContainer.isComplete && !progressContainer.hasError()) { System.out.println("Executing step " + progressContainer.getCurrentStep() + " of " + progressContainer.getTotalSteps() + ": " + progressContainer.getCurrentStepDescription()); progressContainer.waitForUpdate(); } if (progressContainer.hasError()) { System.out.println("Task did not complete because of error: " + progressContainer.getError().toString()); } else { System.out.println("Task complete."); if (progressContainer.getResult() != null) { System.out.println("Result: " + progressContainer.getResult().toString()); } }
A convenience method, blockAndTrace(Level)
, is provided so that the
above can be accomplished with much less effort:
You may also see:ProgressContainer progressContainer = longRunningCommandInvocation(); progressContainer.blockAndTrace(Level.FINER);
Another common use case is to simply collect the ProgressContainers and periodically check them all for updates, get the updated data, and then display or act on it.ProgressContainer progressContainer = longRunningCommandInvocation(); progressContainer.waitForEnd();
Also available is a correlator
, which is a value which can be
optionally set and retrieved by the caller to hold a value that may help
correlate this background task to other items that the caller cares about.
The queue processor does not look at this correlator, it is for use only by
the caller. The default value of the correlator is null.
This class is NLS-enabled using message keys and arguments.
Internal comment: The thread that feeds updates to this object
should always close this object via one of these methods:
setComplete()
,setComplete(Object)
, or
setError(Exception)
. Otherwise there will be a circular
reference between the task and the ProgressContainer that will prevent
garbage collection of both this ProgressContainer and the task that it
references.
Internal comment: This class also supports hiding of the
final error/completion until the feeding thread wishes to call
commit()
. This is helpful when dealing with locks where
the lock is released in a finally
clause and the
commit()
invocation can also be placed in that
finally
clause after the lock release. Note that
updates to the current step cannot be hidden, only the final
result/error. For more information, see the javadoc for
commit()
(package-access method).
Internal comment: Generally only the Task classes will load ProgressContainers with completion and/or error data. So for that reason you won't see ProgressContainers being passed into lower-level methods. For example, if a lower-level method encounters an error condition, it will throw an exception all the way back up to the Task class instead of calling setError(e) itself. In places where you do see ProgressContainers being passed into lower-level methods, it is only for the lower-level method to increment the current step with information available only to the lower-level method.
MacroProgressContainer
Field Summary | |
---|---|
static java.lang.String |
COPYRIGHT_2009_2013
|
Method Summary | |
---|---|
void |
blockAndTrace(java.util.logging.Level level)
A convenience method for waiting for the task to complete and printing the progress of each step. |
void |
follow(ProgressContainer that,
boolean doMergeAtEnd)
Have this ProgressContainer act as a facade to another ProgressContainer. |
java.lang.Object |
getCorrelator()
Get the caller-defined correlator for this object. |
java.util.Date |
getCreationDate()
Get the date this object was created. |
int |
getCurrentStep()
Get the current step number for this task. |
java.lang.String |
getCurrentStepDescription()
Get the textual description of the current step, resolving the message key with the argument value substitution. |
java.lang.Object[] |
getCurrentStepDescriptionArgs()
Get the arguments for the description of the current step. |
java.lang.String |
getCurrentStepDescriptionKey()
Get the key for the description of the current step. |
java.util.Date |
getCurrentStepTimestamp()
Get the timestamp of the most recent update to this object. |
java.lang.Exception |
getError()
Get the Exception that caused the task to end abnormally. |
java.util.Vector |
getEventList()
Returns a Vector of step descriptions with the most recent at the end of the Vector. |
java.lang.Object |
getResult()
If the task was supposed to return a result to the caller, use this method to fetch the result from the task. |
Task |
getTask()
Get the task object (usually a BackgroundTask or Notification) that this ProgressContainer is related to. |
int |
getTotalSteps()
Get the estimated total number of steps for this task. |
boolean |
hasError()
Check if the task ended abnormally. |
boolean |
hasUpdate()
A non-blocking method to check if the object has an update. |
boolean |
isComplete()
Check if the task represented by this object completed successfully. |
void |
merge(ProgressContainer that)
Merge all the results (both result and exception) of another ProgressContainer into this one. |
void |
mergeError(ProgressContainer that)
Merge the error of another ProgressContainer into this one. |
void |
setCorrelator(java.lang.Object correlator)
Set the caller-defined correlator for this object. |
java.lang.String |
toString()
Create a human-readable String representation of this object. |
void |
waitForEnd()
Block and wait for the object to reach "the end", where "the end" is defined as being complete or ending abnormally with an error. |
void |
waitForUpdate()
Block and wait for this object to be updated. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String COPYRIGHT_2009_2013
Method Detail |
---|
public void waitForUpdate() throws java.lang.InterruptedException
hasUpdate()
.
If there is not an error and it is not complete, then the update is regarding a current step.
getCurrentStep()
,
getCurrentStepDescription()
,
isComplete()
,
hasError()
,
hasUpdate()
public void waitForEnd() throws java.lang.InterruptedException
waitForUpdate()
public boolean hasUpdate()
waitForUpdate()
. An
update could consist of an increment of the current step, or a change in
the estimated total number of steps.
Note that this will return false if the object has completed either
successfully or with an error. If you wish to check for those conditions,
use isComplete()
or hasError()
.
Note that waitForUpdate()
will return on these two conditions
plus if the object completes either successfully or with an error. So
waitForUpdate()
behaves a bit differently than this method.
waitForUpdate()
public int getTotalSteps()
hasUpdate
flag for this object.
isComplete()
. To accurately check if this task ended
abnormally with an error, use hasError()
.getCurrentStep()
,
isComplete()
,
hasError()
public Task getTask()
public int getCurrentStep()
hasUpdate
flag for this object.
isComplete()
.getTotalSteps()
,
getCurrentStepDescription()
,
getCurrentStepTimestamp()
public java.lang.String getCurrentStepDescription()
hasUpdate
flag for this object.
getTotalSteps()
,
getCurrentStep()
,
getCurrentStepTimestamp()
,
getCurrentStepDescriptionKey()
,
getCurrentStepDescriptionArgs()
public java.lang.Object[] getCurrentStepDescriptionArgs()
hasUpdate
flag for this object. This
should be used in conjunction with
getCurrentStepDescriptionKey()
if you want the values
separately, or just call getCurrentStepDescription()
which will
resolve the message key and substitute the argument values.
getCurrentStepDescriptionKey()
,
getCurrentStepDescription()
public java.lang.String getCurrentStepDescriptionKey()
hasUpdate
flag for this object. This should be used
in conjunction with getCurrentStepDescriptionArgs()
if you want
the key separately, or just call getCurrentStepDescription()
which will resolve the message key and substitute the argument values.
getCurrentStepDescriptionArgs()
,
getCurrentStepDescription()
public java.util.Date getCurrentStepTimestamp()
hasUpdate
flag for this object.
public boolean isComplete()
getResult()
. It will
return false if the task is still in process or if it ended
abnormally with an error. To check if it ended with an error, use
hasError()
. Calling this method will not clear the
hasUpdate
flag for this object.hasError()
,
getResult()
public java.lang.Object getResult()
isComplete
returns true
. Calling
this method will clear the hasUpdate
flag for this object.
isComplete()
public boolean hasError()
getError()
. The isComplete
flag will be
set to false. This will return false if the task is still
executing or if it completed successfully. Calling this method
will not clear the hasUpdate
flag for this object.getError()
,
isComplete()
public java.lang.Exception getError()
hasError
flag is true.
Calling this method will clear the hasUpdate
flag for this
object.
hasError()
public void setCorrelator(java.lang.Object correlator)
hasUpdate
flag for this object.
correlator
- a caller-defined correlation value for this object.
This is a value which can be optionally set and retrieved by the
caller to store a value that may help correlate this background
task to other items that the caller cares about. The queue
processor does not look at this correlator, it is for use only by
the caller. The default value of the correlator is null.getCorrelator()
public java.lang.Object getCorrelator()
hasUpdate
flag for this object.
setCorrelator(Object)
.setCorrelator(Object)
public java.util.Date getCreationDate()
hasUpdate
flag for this object.
public void blockAndTrace(java.util.logging.Level level) throws java.lang.InterruptedException, java.lang.Exception
level
- the log level at which to generate the text messagespublic void follow(ProgressContainer that, boolean doMergeAtEnd)
this
the 2nd ProgressContainer and that
the
1st ProgressContainer. Even though the 1st one may be partially complete,
the 2nd one will look at how many more steps the 1st one has and will
follow it along until the 1st one completes. Whatever result or exception
that the 1st one finished with, that data will be copied into the 2nd one -
this is what I call a "merge". This method will block until the 1st one
finishes.
that
- the first ProgressContainer to follow.doMergeAtEnd
- if true, will copy the result/exception data from the
first one into the second one (this one). You would want to do
this if the second one isn't going to follow any more
ProgressContainers.merge(ProgressContainer)
public void merge(ProgressContainer that)
that
has an error or a result, then copy it into this one.
that
- the ProgressContainer from which to copy the exception or
result object frommergeError(ProgressContainer)
public void mergeError(ProgressContainer that)
that
has an error, then copy it into
this one.
that
- the ProgressContainer from which to copy the exception frompublic java.lang.String toString()
toString
in class java.lang.Object
public java.util.Vector getEventList()
hasError()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |