mckay.utilities.gui.progressbars
Class DoubleProgressBarTaskMonitor

java.lang.Object
  extended by mckay.utilities.gui.progressbars.DoubleProgressBarTaskMonitor
Direct Known Subclasses:
DoubleProgressBarTaskCoordinator

public abstract class DoubleProgressBarTaskMonitor
extends java.lang.Object

An abstract class that is used by a DoubleProgressBarDialog windows in order to perform the processing that is measured by that window as well as to keep it updated. This involves two progress bars, one which shows the progress of an overall task, and one which shows the progress of a subtask that is part of this overall task.

All parts of this abstract class are implemented here except for the go method. This method should use a SwingWorker object to start and perform the task to be performed. The go method should also keep the fields of this DoubleProgressBarTaskMonitor object updated so that they can be queried by the calling DoubleProgressBarDialog.

It is assumed that all sub-tasks will take an equal amount of time which, while incorrect in most cases, is assumed to be close enough

One part of the class implemented here essentially provides an interface for the calling DoubleProgressBarTaskMonitor and calculates the time elapsed and the estimated processing time remaining. The other part of this class provides methods that the extending class can make use of to keep the progress bar fields updated. These methods consist of (aside from the abstract go method) the initializeOverallTask, startNewSubTask, setSubTaskProgressValue and markTaskComplete methods.


Field Summary
protected  int bottom_current_amount_completed
          The number of sub-tasks completed so far in the bottom task.
protected  int bottom_length_of_task
          The total number of sub-tasks in the bottom task.
protected  java.lang.String bottom_progress_message
          Messages to be displayed for the bottom bar.
protected  long bottom_time_started
          The time when the bottom task was started.
protected  boolean new_bottom_task_started
          Whether or not a new progress bar needs to be started for the bottom task.
protected  boolean new_top_task_started
          Whether or not a new progress bar needs to be started for the top task.
protected  long overall_end_time
          The time when all processing finishes.
protected  long overall_start_time
          The time when processing begins.
protected  long[] sub_task_durations
          An array keeping track of how long each sub-task took.
protected  int sub_task_index
          The index of the sub task currently being processed.
protected  java.lang.String[] sub_task_names
          An array keeping track of the name of each sub-task.
protected  boolean task_canceled
          Whether or not processing has been cancelled.
protected  boolean task_completed
          Whether or not processing has been completed.
protected  int top_current_amount_completed
          The number of sub-tasks completed so far in the top task.
protected  int top_length_of_task
          The total number of sub-tasks in the top task.
protected  java.lang.String top_progress_message
          Messages to be displayed for the top bar.
protected  long top_time_started
          The time when the top task was started.
 
Constructor Summary
DoubleProgressBarTaskMonitor()
          Basic constructor that sets fields to defaluts.
 
Method Summary
protected  java.lang.String findTimeWithProperUnits(int seconds)
          Takes in a number of seconds and returns the appropriatly formatted amount of time corresponding to this based on how many seconds there are.
 int getBottomCurrentAmountCompleted()
          Called from a DoubleProgressBarDialog to find out how many tasks for the sub-task progress bar have been done.
 int getBottomLengthOfTask()
          Called from a DoubleProgressBarDialog to find out how many tasks in the sub-task progress bar remain to be done.
 java.lang.String getBottomTextMessage()
          Returns a string indicating, for the sub-task progress bar, how much time has already passed and the estimated time remaining.
 java.lang.String[][] getProcessingTimeLogs(boolean want_raw_milliseconds)
          Returns a breakdown of how long each subtask took to complete.
 int getTopCurrentAmountCompleted()
          Called from a DoubleProgressBarDialog to find out how many tasks for the overall progress bar have been done.
 int getTopLengthOfTask()
          Called from a DoubleProgressBarDialog to find out how many tasks in the overall progress bar remain to be done.
 java.lang.String getTopTextMessage()
          Returns a string indicating, for the overall progress bar, how much time has already passed and the estimated time remaining.
abstract  void go()
          Called to start the overall task that the progress bar is monitoring.
 void initializeOverallTask(int number_of_subtasks)
          Initializes the overall task.
 boolean isCancelled()
          Called to check if the overall task has been cancelled.
 boolean isDone()
          Called to find out if the overall task has completed.
 void markTaskComplete()
          Called if the overall task is complete.
 void setSubTaskProgressValue(int progress_value)
          Update the progress of the bottom progress bar.
 boolean startNewBottomProgress()
          Sets the new_bottom_task_started field to false and returns its previous value.
 void startNewSubTask(int tasks_in_subtask, java.lang.String sub_task_name)
          Called when a new sub-task is being started (i.e.
 boolean startNewTopProgress()
          Sets the new_top_task_started field to false and returns its previous value.
 void stop()
          Called if the overall task is cancelled.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

overall_start_time

protected long overall_start_time
The time when processing begins.


overall_end_time

protected long overall_end_time
The time when all processing finishes.


sub_task_index

protected int sub_task_index
The index of the sub task currently being processed. Used for the sub_task_names and sub_task_durations arrays.


sub_task_names

protected java.lang.String[] sub_task_names
An array keeping track of the name of each sub-task.


sub_task_durations

protected long[] sub_task_durations
An array keeping track of how long each sub-task took. The entries correspond to those of sub_task_names.


new_top_task_started

protected boolean new_top_task_started
Whether or not a new progress bar needs to be started for the top task.


new_bottom_task_started

protected boolean new_bottom_task_started
Whether or not a new progress bar needs to be started for the bottom task.


top_length_of_task

protected int top_length_of_task
The total number of sub-tasks in the top task.


bottom_length_of_task

protected int bottom_length_of_task
The total number of sub-tasks in the bottom task.


top_current_amount_completed

protected int top_current_amount_completed
The number of sub-tasks completed so far in the top task.


bottom_current_amount_completed

protected int bottom_current_amount_completed
The number of sub-tasks completed so far in the bottom task.


top_time_started

protected long top_time_started
The time when the top task was started.


bottom_time_started

protected long bottom_time_started
The time when the bottom task was started.


top_progress_message

protected java.lang.String top_progress_message
Messages to be displayed for the top bar.


bottom_progress_message

protected java.lang.String bottom_progress_message
Messages to be displayed for the bottom bar.


task_completed

protected boolean task_completed
Whether or not processing has been completed.


task_canceled

protected boolean task_canceled
Whether or not processing has been cancelled.

Constructor Detail

DoubleProgressBarTaskMonitor

public DoubleProgressBarTaskMonitor()
Basic constructor that sets fields to defaluts.

Method Detail

go

public abstract void go()
Called to start the overall task that the progress bar is monitoring. Sets up a SwingWorker object to carry out the thread and sets time started. Keeps the appropriate fields updated using the startNewSubTask, setSubTaskProgressValue and markTaskComplete methods. The first thing that this method should do is call the initializeOverallTask class.


initializeOverallTask

public void initializeOverallTask(int number_of_subtasks)
Initializes the overall task. Should be the first thing called by the go method in extensions of this class.

Parameters:
number_of_subtasks - The number of subtasks in the overall job that is being processed (i.e. the number of increments to divide the top progress bar into.

startNewSubTask

public void startNewSubTask(int tasks_in_subtask,
                            java.lang.String sub_task_name)
Called when a new sub-task is being started (i.e. when the bottom progress bar is restarting). Makes the appropriate modifications to both of the progress bars.

Parameters:
tasks_in_subtask - The number of tasks that make up this new sub-task (i.e. how many sections to divide the bottom progress bar into).
sub_task_name - The name of this overall sub-task.

setSubTaskProgressValue

public void setSubTaskProgressValue(int progress_value)
Update the progress of the bottom progress bar.

Parameters:
progress_value - How many parts of the current sub-task have been completed.

markTaskComplete

public void markTaskComplete()
Called if the overall task is complete. Stops processing and records final task times.


getProcessingTimeLogs

public java.lang.String[][] getProcessingTimeLogs(boolean want_raw_milliseconds)
Returns a breakdown of how long each subtask took to complete.

Parameters:
want_raw_milliseconds - If this is true, the processing times are returned as milliseconds. If it is false, then they are formatted based on duration.
Returns:
The processing time logs. The first dimension corresponds to the the task number (there is also one additional entry at the end for the overall combined processing time). The second dimension is as follows: entry 0 provides the name of the sub-task and entry 1 details how long it took to complete that sub-task.

stop

public void stop()
Called if the overall task is cancelled. Stops processing.


isCancelled

public boolean isCancelled()
Called to check if the overall task has been cancelled. This method is typically called by DoubleProgressBarDialog objects.

Returns:
Whether or not the task is marked as cancelled.

isDone

public boolean isDone()
Called to find out if the overall task has completed. This method is typically called by DoubleProgressBarDialog objects.

Returns:
Whether all processing is finished.

startNewTopProgress

public boolean startNewTopProgress()
Sets the new_top_task_started field to false and returns its previous value. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The previous value of the new_top_task_started field.

startNewBottomProgress

public boolean startNewBottomProgress()
Sets the new_bottom_task_started field to false and returns its previous value. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The previous value of the new_bottom_task_started field.

getTopLengthOfTask

public int getTopLengthOfTask()
Called from a DoubleProgressBarDialog to find out how many tasks in the overall progress bar remain to be done. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The number of tasks in the overall progress bar remain to be done.

getBottomLengthOfTask

public int getBottomLengthOfTask()
Called from a DoubleProgressBarDialog to find out how many tasks in the sub-task progress bar remain to be done. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The number of tasks in the sub-task progress bar remain to be done.

getTopCurrentAmountCompleted

public int getTopCurrentAmountCompleted()
Called from a DoubleProgressBarDialog to find out how many tasks for the overall progress bar have been done. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The number of tasks for the overall progress bar have been done.

getBottomCurrentAmountCompleted

public int getBottomCurrentAmountCompleted()
Called from a DoubleProgressBarDialog to find out how many tasks for the sub-task progress bar have been done. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The number of tasks for the sub-task progress bar have been done.

getTopTextMessage

public java.lang.String getTopTextMessage()
Returns a string indicating, for the overall progress bar, how much time has already passed and the estimated time remaining. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The informative string.

getBottomTextMessage

public java.lang.String getBottomTextMessage()
Returns a string indicating, for the sub-task progress bar, how much time has already passed and the estimated time remaining. This method is typically called by DoubleProgressBarDialog objects.

Returns:
The informative string.

findTimeWithProperUnits

protected java.lang.String findTimeWithProperUnits(int seconds)
Takes in a number of seconds and returns the appropriatly formatted amount of time corresponding to this based on how many seconds there are. Some rounding takes place.

Parameters:
seconds - The number of seconds to base the formatted string on.
Returns:
The formatted number of seconds.