com.microsoft.tfs.util.tasks
Interface TaskMonitor

All Known Implementing Classes:
FileProcessingProgressMonitorAdapter, NullTaskMonitor

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.

See Also:
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

begin

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.

Parameters:
taskName - the name of the task that is beginning, or null if there is no task name
totalWork - the total amount of work units that this task will take (must be non-negative)

beginWithUnknownTotalWork

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.

Parameters:
taskName - the name of the task that is beginning, or null if there is no task name

done

void 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.


isCanceled

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.

Returns:
true if cancelation has been requested for this task

setCanceled

void setCanceled()

Sets the cancel state to true for the task this TaskMonitor is monitoring.


worked

void worked(int amount)
Called by the task that this 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.

Parameters:
amount - a non-negative, non-cumulative amount of work units

setTaskName

void setTaskName(java.lang.String taskName)
Called to set the task name of the task being monitored by this 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.

Parameters:
taskName - the task name as described above, or null to clear the task name

setCurrentWorkDescription

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. 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.

Parameters:
description - the current work description as described above, or null to clear the current work description

newSubTaskMonitor

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.

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.

Parameters:
amount - the amount of work units of the main task that the sub-task will use up (must be non-negative)
Returns:
a new TaskMonitor instance to be used for a sub-task as described above (never null)


© 2015 Microsoft. All rights reserved.