net.charlesames.utility.common
Class ProgressMonitor

java.lang.Object
  net.charlesames.utility.common.ProgressMonitor

public class ProgressMonitor
extends java.lang.Object

Common interface for tracking the status and portion-completed condition of a process. All internal variables are declared as volatile, for thread safety. When the process starts running, it should set ProgressMonitor.Goal to the total number of steps required for completion, ProgressMonitor.Current to 0, and ProgressMonitor.Status to RUNNING.

Each time the process achieves a step it should update ProgressMonitor.Current. ProgressMonitor.ActivityMessage can also be used to communicate what the process is doing.

If the process completes successfully, it should call ProgressMonitor.complete().

If the process completes with an error it should call ProgressMonitor.error() with a suitable message.

With one exception, only the process being monitored should be updating ProgressMonitor properties. The exception is ProgressMonitor.kill(). This method should be called by the monitoring thread when the end user wishes to cancel the process being monitored. The process being monitored should periodically consult ProgressMonitor.isPermitted(). When this returns false, the process should shut down all activity, then call ProgressMonitor.cancel().

Author:

Charles Ames

Nested Class Summary

static class

ProgressMonitor.Status ProgressMonitor status conditions.

Constructor Summary

ProgressMonitor()
Constructor for ProgressMonitor instances.

ProgressMonitor(java.lang.Thread thread)
Constructor for ProgressMonitor instances.

Method Summary

void	appendActivityMessage(java.lang.String message)
void	cancel() Set ProgressMonitor.Status to CANCELED.
void	complete() Set ProgressMonitor.Status to COMPLETE; set ProgressMonitor.Current to ProgressMonitor.Goal; clear ProgressMonitor.ErrorMessage; and set ProgressMonitor.ActivityMessage to "Done".
void	error(java.lang.String message) Set ProgressMonitor.Status to ERROR; and set ProgressMonitor.ErrorMessage to the message parameter.
java.lang.String	getActivityMessage() Get the activity message.
java.lang.String	getCompletedMessage() Get the completed message.
double	getCurrent()
java.lang.String	getErrorMessage()
double	getGoal()
int	getPhase() Get the phase.
ProgressMonitor.Status	getStatus()
java.lang.Thread	getThread() Get the thread whose progress is being monitored.
void	incrementCurrent(double increment) Increment the current progress amount.
boolean	isComplete()
boolean	isPermitted()
boolean	isRunning()
void	kill() Set ProgressMonitor.Status to KILLED.
void	setActivityMessage(java.lang.String message)
void	setCompletedMessage(java.lang.String message)
void	setCurrent(double current) Update the current progress amount.
void	setGoal(double goal) Update the progress limit.
void	setPhase(int phase) Set the phase.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProgressMonitor

public ProgressMonitor()

Constructor for ProgressMonitor instances.

ProgressMonitor

public ProgressMonitor(java.lang.Thread thread)

Constructor for ProgressMonitor instances.

Parameters:

thread - The thread whose progress is being monitored.

Method Detail

getThread

public java.lang.Thread getThread()

Get the thread whose progress is being monitored.

Returns:

The thread whose progress is being monitored.

getPhase

public int getPhase()

Get the phase.

Returns:

The assigned phase.

setPhase

public void setPhase(int phase)

Set the phase.

Parameters:

phase - The intended phase.

getCurrent

public double getCurrent()

Returns:

A number indicating the current progress.

setCurrent

public void setCurrent(double current)

Update the current progress amount. This method should only be called by the process thread.

Parameters:

current - A number indicating the current progress. Ranges from 0 to ProgressMonitor.Goal.

incrementCurrent

public void incrementCurrent(double increment)

Increment the current progress amount. This method should only be called by the process thread.

Parameters:

increment - A number indicating the change in current progress.

getGoal

public double getGoal()

Returns:

A number indicating the limit that the current progress amount will reach, should the process complete successfully.

setGoal

public void setGoal(double goal)

Update the progress limit. This method should only be called by the process thread, and typically just before the process thread sets the ProgressMonitor.Status to RUNNING.

Parameters:

goal - A number indicating the current progress. Ranges from 0 to ProgressMonitor.Goal.

isPermitted

public boolean isPermitted()

Returns:

True if ProgressMonitor.Status is ProgressMonitor.Status.RUNNING; false otherwise.

isComplete

public boolean isComplete()

Returns:

True if ProgressMonitor.Status is ProgressMonitor.Status.COMPLETE; false otherwise.

complete

public void complete()

Set ProgressMonitor.Status to COMPLETE; set ProgressMonitor.Current to ProgressMonitor.Goal; clear ProgressMonitor.ErrorMessage; and set ProgressMonitor.ActivityMessage to "Done". This method should only be called by the process thread.

error

public void error(java.lang.String message)

Set ProgressMonitor.Status to ERROR; and set ProgressMonitor.ErrorMessage to the message parameter. This method should only be called by the process thread.

Parameters:

message - Text to be presented in ProgressMonitor.ErrorMessage.

kill

public void kill()

Set ProgressMonitor.Status to KILLED. This method should only be called by the monitoring thread.

cancel

public void cancel()

Set ProgressMonitor.Status to CANCELED. This method should only be called by the process thread, and only when ProgressMonitor.Status is KILLED.

getStatus

public ProgressMonitor.Status getStatus()

Returns:

The status of the process being monitored.

isRunning

public boolean isRunning()

Returns:

True if ProgressMonitor.Status is one of INITIALIZING, RUNNING, or KILLED.

getErrorMessage

public java.lang.String getErrorMessage()

Returns:

ProgressMonitor.ErrorMessage.

getActivityMessage

public java.lang.String getActivityMessage()

Get the activity message.

Returns:

The text to be displayed by ProgressMonitor.ActivityMessage while the task is running.

setActivityMessage

public void setActivityMessage(java.lang.String message)

Parameters:

message - The text to be displayed by ProgressMonitor.ActivityMessage while the task is running.

appendActivityMessage

public void appendActivityMessage(java.lang.String message)

Parameters:

message - The text to be displayed by ProgressMonitor.ActivityMessage while the task is running.

getCompletedMessage

public java.lang.String getCompletedMessage()

Get the completed message.

Returns:

The text to be displayed by ProgressMonitor.ActivityMessage after the task has completed successfully.

setCompletedMessage

public void setCompletedMessage(java.lang.String message)

Parameters:

message - The text to be displayed by ProgressMonitor.ActivityMessage after the task has completed successfully.