|
||||||||||
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-TaskMonitor
s
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 |