de.cau.cs.kieler.core.alg
Class BasicProgressMonitor

java.lang.Object
  extended by de.cau.cs.kieler.core.alg.BasicProgressMonitor
All Implemented Interfaces:
IKielerProgressMonitor
Direct Known Subclasses:
KielerProgressMonitor

public class BasicProgressMonitor
extends Object
implements IKielerProgressMonitor

Base class for implementations of progress monitors. This class performs execution time measurement, keeps track of the amount of completed work, and handles sub-tasks properly.

Rating proposed yellow
(2009-12-11) msp

Field Summary
 
Fields inherited from interface de.cau.cs.kieler.core.alg.IKielerProgressMonitor
UNKNOWN_WORK
 
Constructor Summary
BasicProgressMonitor()
          Creates a progress monitor with infinite number of hierarchy levels.
BasicProgressMonitor(int themaxLevels)
          Creates a progress monitor with the given maximal number of hierarchy levels.
 
Method Summary
 void begin(String name, float thetotalWork)
          Notifies that the task will begin after this method has been called.
protected  void doBegin(String name, float newTotalWork, boolean topInstance, int maxHierarchyLevels)
          Invoked when a task begins, to be overridden by subclasses.
protected  void doDone(boolean topInstance, int maxHierarchyLevels)
          Invoked when a task ends, to be overridden by subclasses.
 void done()
          Notifies that the current task is done and closes the monitor.
protected  BasicProgressMonitor doSubTask(float work, int maxHierarchyLevels)
          Invoked when a sub-task is created, to be overridden by subclasses.
protected  void doWorked(float work, float thecompletedWork, boolean topInstance)
          Invoked when work is done for this progress monitor, to be overridden by subclasses.
 double getExecutionTime()
          Returns the measured execution time for the task associated with this monitor.
 IKielerProgressMonitor getParentMonitor()
          Returns the parent monitor.
 List<IKielerProgressMonitor> getSubMonitors()
          Returns a list of all monitors associated with direct sub-tasks.
 String getTaskName()
          Returns the name of the task associated with this progress monitor.
 boolean isCanceled()
          This implementation always returns false.
 IKielerProgressMonitor subTask(float work)
          Creates a new sub-task that will complete the given amount of work units when it is done.
 void worked(float work)
          Notifies that the given number of work units has been completed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BasicProgressMonitor

public BasicProgressMonitor()
Creates a progress monitor with infinite number of hierarchy levels.


BasicProgressMonitor

public BasicProgressMonitor(int themaxLevels)
Creates a progress monitor with the given maximal number of hierarchy levels. If the number is negative, the hierarchy levels are infinite. Otherwise progress is reported to parent monitors only up to the specified number of levels.

Parameters:
themaxLevels - the maximal number of hierarchy levels for which progress is reported
Method Detail

begin

public final void begin(String name,
                        float thetotalWork)
Notifies that the task will begin after this method has been called. This method will have no effect is the monitor is closed.

Specified by:
begin in interface IKielerProgressMonitor
Parameters:
name - readable name of the new task
thetotalWork - total amount of work units, or UNKNOWN_WORK if this is not specified

doBegin

protected void doBegin(String name,
                       float newTotalWork,
                       boolean topInstance,
                       int maxHierarchyLevels)
Invoked when a task begins, to be overridden by subclasses. This implementation does nothing.

Parameters:
name - task name
newTotalWork - total amount of work for the new task
topInstance - if true, this progress monitor is the top instance
maxHierarchyLevels - the maximal number of reported hierarchy levels, or -1 for infinite levels

done

public final void done()
Notifies that the current task is done and closes the monitor. This method may be called multiple times, without any effect after the first time.

Specified by:
done in interface IKielerProgressMonitor

doDone

protected void doDone(boolean topInstance,
                      int maxHierarchyLevels)
Invoked when a task ends, to be overridden by subclasses. This implementation does nothing.

Parameters:
topInstance - if true, this progress monitor is the top instance
maxHierarchyLevels - the maximal number of reported hierarchy levels, or -1 for infinite levels

getExecutionTime

public final double getExecutionTime()
Returns the measured execution time for the task associated with this monitor.

Specified by:
getExecutionTime in interface IKielerProgressMonitor
Returns:
number of seconds used for execution

getSubMonitors

public final List<IKielerProgressMonitor> getSubMonitors()
Returns a list of all monitors associated with direct sub-tasks.

Specified by:
getSubMonitors in interface IKielerProgressMonitor
Returns:
list of sub-task monitors

getParentMonitor

public final IKielerProgressMonitor getParentMonitor()
Returns the parent monitor. The parent monitor is the one for which a call to #subTask(int) resulted in the current monitor instance.

Specified by:
getParentMonitor in interface IKielerProgressMonitor
Returns:
the parent monitor, or null if there is none

getTaskName

public String getTaskName()
Returns the name of the task associated with this progress monitor.

Specified by:
getTaskName in interface IKielerProgressMonitor
Returns:
task name

isCanceled

public boolean isCanceled()
This implementation always returns false.

Specified by:
isCanceled in interface IKielerProgressMonitor
Returns:
false

subTask

public final IKielerProgressMonitor subTask(float work)
Creates a new sub-task that will complete the given amount of work units when it is done. The sub-task begins when #begin(String, int) is called for the new progress monitor instance, and it ends when IKielerProgressMonitor.done() is called for that instance.

Specified by:
subTask in interface IKielerProgressMonitor
Parameters:
work - number of work units that are completed in the current monitor instance when the sub-task is done
Returns:
a progress monitor for the new sub-task, or null if the monitor is closed

doSubTask

protected BasicProgressMonitor doSubTask(float work,
                                         int maxHierarchyLevels)
Invoked when a sub-task is created, to be overridden by subclasses. This implementation creates a new BasicProgressMonitor instance.

Parameters:
work - amount of work that is completed in the current monitor instance when the sub-task ends
maxHierarchyLevels - the maximal number of reported hierarchy levels for the parent progress monitor, or -1 for infinite levels
Returns:
a new progress monitor instance

worked

public final void worked(float work)
Notifies that the given number of work units has been completed. This method will have no effect is the monitor is closed.

Specified by:
worked in interface IKielerProgressMonitor
Parameters:
work - number of work units

doWorked

protected void doWorked(float work,
                        float thecompletedWork,
                        boolean topInstance)
Invoked when work is done for this progress monitor, to be overridden by subclasses. This implementation does nothing.

Parameters:
work - amount of work that has just been done
thecompletedWork - total number of work that is done for this task
topInstance - if true, this progress monitor is the top instance