|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
public interface TaskMonitor
A TaskMonitor provides access to several services useful for
implementing long-running tasks. First, a TaskMonitor allows a
long-running task to report on its progress: the total amount of work the
task will do, and how much of that work has been done so far. Secondly, a
TaskMonitor allows a long-running task to check whether cancelation
has been requested: if it has, the task can finish early.
Both of these services are used to communicate across layers of an
application. Typically, a user interface layer will provide a
TaskMonitor and a lower layer will implement a long-running task and
consume the TaskMonitor. The user interface layer will receive
progress messages from the lower layer through the TaskMonitor and
display some sort of a UI around the progress. The lower layer will receive
cancelation messages from the user interface layer and respond to them
appropriately.
The TaskMonitorService class is used to manage instances of
TaskMonitor. Typically, the user interface layer will use
TaskMonitorService to make a TaskMonitor instance available,
and the lower layer will use TaskMonitorService to obtain the
TaskMonitor instance to consume.
Note that the cancelation mechanism provided by TaskMonitor is poll
based. In order to be cancel-aware, the long-running task must occasionally
call the isCanceled() method and return early if true
is returned.
There are two different String descriptions associated with a
long-running task being monitored: a task name and a current work
description. Think of these as a main header and a sub header. Many tasks
are based on iterating over a number of work items and doing something with
each work item. For these tasks, the task name would be something general
(for example "Downloading Files") and the current work description would be
changed with each work item that was processed (for example the name of an
individual file). Typically, the task name will be set once when either
begin(String, int) or beginWithUnknownTotalWork(String) is
called, and the current work description will be set many times (when
setCurrentWorkDescription(String) is called).
TaskMonitor supports the common pattern of sub-tasks that have their
own TaskMonitor instance. To obtain a new TaskMonitor
instance for a sub-task, call the newSubTaskMonitor(int) method.
Note that if a TaskMonitor is canceled any sub-TaskMonitors
will also be canceled. This is true whether the TaskMonitor was
canceled through the interface by calling setCanceled() or by some
other means. Also, if a sub-TaskMonitor is canceled all
TaskMonitor instances in the sub-task tree up to the original parent
are canceled.
TaskMonitorService| Method Summary | |
|---|---|
void |
begin(java.lang.String taskName,
int totalWork)
Called to indicate the start of the task that this TaskMonitor
instance is monitoring. |
void |
beginWithUnknownTotalWork(java.lang.String taskName)
Called to indicate the start of the task that this TaskMonitor
instance is monitoring. |
void |
done()
Called to indicate the end of the task that this TaskMonitor
instance is monitoring. |
boolean |
isCanceled()
Called to test whether cancelation has been requested for the task that this TaskMonitor instance is monitoring. |
TaskMonitor |
newSubTaskMonitor(int amount)
Called to obtain a new TaskMonitor instance to be used in a
sub-task of the task being monitored by this TaskMonitor
instance. |
void |
setCanceled()
Sets the cancel state to true for the task this TaskMonitor is
monitoring. |
void |
setCurrentWorkDescription(java.lang.String description)
Called to set a more detailed description of the current work being done than the task name alone gives. |
void |
setTaskName(java.lang.String taskName)
Called to set the task name of the task being monitored by this TaskMonitor. |
void |
worked(int amount)
Called by the task that this TaskMonitor is monitoring to report
progress. |
| Method Detail |
|---|
void begin(java.lang.String taskName,
int totalWork)
Called to indicate the start of the task that this TaskMonitor
instance is monitoring. This method is called when the total number of
work units for the task are known.
Either this method or the beginWithUnknownTotalWork(String)
method must be called only once per TaskMonitor instance, and one
or the other must be called before other methods on the instance are
called.
taskName - the name of the task that is beginning, or null if
there is no task nametotalWork - the total amount of work units that this task will take (must be
non-negative)void beginWithUnknownTotalWork(java.lang.String taskName)
Called to indicate the start of the task that this TaskMonitor
instance is monitoring. This method is called when the total number of
work units for the task is not known.
Either this method or the begin(String, int) method must be
called only once per TaskMonitor instance, and one or the other
must be called before other methods on the instance are called.
taskName - the name of the task that is beginning, or null if
there is no task namevoid done()
Called to indicate the end of the task that this TaskMonitor
instance is monitoring. This method must be called, even if the
task aborts with an error or is canceled.
It is safe to call this method multiple times.
boolean isCanceled()
Called to test whether cancelation has been requested for the task that
this TaskMonitor instance is monitoring.
To be cancelation-aware, the task should poll this method at regular
intervals. If true is returned, the task should return early
as quickly as possible.
true if cancelation has been requested for this taskvoid setCanceled()
Sets the cancel state to true for the task this TaskMonitor is
monitoring.
void worked(int amount)
TaskMonitor is monitoring to report
progress. This method is typically called multiple times during the task.
Each time the number of work units that have been completed since the
last call to this method are passed. In other words, the number of work
units reported to this method must be non-cumulative.
amount - a non-negative, non-cumulative amount of work unitsvoid setTaskName(java.lang.String taskName)
TaskMonitor. Normally there is no reason to call this method,
since the task name is set by either the begin(String, int) or
beginWithUnknownTotalWork(String) methods and generally remains
constant throughout the lifetime of the task.
taskName - the task name as described above, or null to clear
the task namevoid setCurrentWorkDescription(java.lang.String description)
Called to set a more detailed description of the current work being done
than the task name alone gives. The current work description is an
additional description above and beyond the task name that is specified
in the begin(String, int),
beginWithUnknownTotalWork(String), and/or
setTaskName(String) methods.
Many UI implementations of TaskMonitor will render the task name
as a header and the current work description as a sub-header. Other UI
implementations may choose to ignore the current work description or to
let it override the task name.
description - the current work description as described above, or
null to clear the current work descriptionTaskMonitor newSubTaskMonitor(int amount)
Called to obtain a new TaskMonitor instance to be used in a
sub-task of the task being monitored by this TaskMonitor
instance.
Note that every call to this method results in a new TaskMonitor
instance, and all of the TaskMonitor rules apply to each
instance. Specifically, one of the begin methods should be
called on the new instance, and the done() method must be called
on the new instance.
Each sub-TaskMonitor uses up sub number of work units of its
parent TaskMonitor. This number is specified as the
amount argument to this method. The sub-TaskMonitor
will have its own number of total work units (specified by the
begin(String, int) method) and internally sub-task progress will
be scaled into main-task progress.
amount - the amount of work units of the main task that the sub-task will
use up (must be non-negative)
TaskMonitor instance to be used for a sub-task as
described above (never null)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||