com.microsoft.tfs.util.tasks
Class TaskMonitorService

java.lang.Object
  extended by com.microsoft.tfs.util.tasks.TaskMonitorService

public class TaskMonitorService
extends java.lang.Object

TaskMonitorService is a service that is used to manage TaskMonitor instances. Upper layer code uses TaskMonitorService to make TaskMonitors available to lower layer code. Lower layer code that implements a long-running task uses TaskMonitorService to obtain a TaskMonitor instance to use for the task.

TaskMonitorService exists for two reasons. First, it ensures that TaskMonitors can be passed across layers without having to explicitly pass them by method arguments from layer to layer. This is accomplished through the use of thread local storage. The upper layer that makes a task monitor available must run on the same thread as the lower layer that retrieves the TaskMonitor.

The second reason the TaskMonitorService exists is to decouple the layer that produces a TaskMonitor from the layer that consumes it. Either layer may be made TaskMonitor-aware without the other layer being TaskMonitor aware. If the upper layer produces a TaskMonitor and nothing consumes it, no progress monitoring or cancelation will occur but everything will still work. If the lower layer asks for a TaskMonitor and one has not been set, a dummy implementation is returned.

Within each thread, the TaskMonitorService is stack based. Each TaskMonitor producer calls pushTaskMonitor(TaskMonitor) to add a TaskMonitor to the service. This call must be matched by a call to popTaskMonitor(), which should occur in the same layer that pushed it. The stack-based implementation is intended mostly to support sub-tasking in which sub-TaskMonitors are pushed on top of their parents.

See Also:
TaskMonitor

Method Summary
static TaskMonitor getTaskMonitor()
          Called to retrieve a TaskMonitor from this TaskMonitorService.
static TaskMonitor popTaskMonitor()
           Called to pop a TaskMonitor from this thread's TaskMonitor stack.
static TaskMonitor popTaskMonitor(boolean callDone)
          Called to pop a TaskMonitor from this thread's TaskMonitor stack.
static void pushTaskMonitor(TaskMonitor taskMonitor)
          Called to push a TaskMonitor onto this thread's TaskMonitor stack.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getTaskMonitor

public static TaskMonitor getTaskMonitor()
Called to retrieve a TaskMonitor from this TaskMonitorService. This method will always return a usable TaskMonitor, even if one has not been set into the service.

Returns:
a TaskMonitor to use (never null)

pushTaskMonitor

public static void pushTaskMonitor(TaskMonitor taskMonitor)
Called to push a TaskMonitor onto this thread's TaskMonitor stack. This call must be matched by a call to popTaskMonitor(). This requirement implies the use of try/finally to satisfy it.

Parameters:
taskMonitor - a TaskMonitor to push (must not be null)

popTaskMonitor

public static TaskMonitor popTaskMonitor()

Called to pop a TaskMonitor from this thread's TaskMonitor stack. This call must be matched with a previous call to pushTaskMonitor(TaskMonitor). This requirement implies the use of try/finally to satisfy it.

Before this method returns, TaskMonitor.done() is called on the popped TaskMonitor. This is almost always safe and the right thing to do (done() can be safely called multiple times). In the rare case that this is not desired, call popTaskMonitor(boolean) instead.

Returns:
the TaskMonitor that was popped off the stack

popTaskMonitor

public static TaskMonitor popTaskMonitor(boolean callDone)
Called to pop a TaskMonitor from this thread's TaskMonitor stack. This call must be matched with a previous call to pushTaskMonitor(TaskMonitor). This requirement implies the use of try/finally to satisfy it.

Parameters:
callDone - if true, TaskMonitor.done() will be called on the popped TaskMonitor before it is returned
Returns:
the TaskMonitor that was popped off the stack


© 2015 Microsoft. All rights reserved.