cytoscape.task
Interface TaskMonitor

All Known Implementing Classes:

JTask

public interface TaskMonitor

Interface for monitoring the progress of a task.

Method Summary

void	setEstimatedTimeRemaining(long time) This is a hook for a child process to report to its parent application estimated time until task completion.
void	setException(Throwable t, String userErrorMessage) Indicates to a parent application that a task has encountered an error while processing.
void	setException(Throwable t, String userErrorMessage, String recoveryTip) Indicates to a parent application that a task has encountered an error while processing.
void	setPercentCompleted(int percent) This is a hook for a child process to report to its parent application what percentage of a task it has completed.
void	setStatus(String message) This is a hook for a child process to report to its parent application a short one-line text description (not exceeding, say, 60 characters, even though that is not enforced) of the current phase of processing.

Method Detail

setPercentCompleted

void setPercentCompleted(int percent)
                         throws IllegalThreadStateException,
                                IllegalArgumentException

This is a hook for a child process to report to its parent application what percentage of a task it has completed.

Typically, the parent application implements this method and offers it as a hook to its child process. A child process may make an educated guess as to what percentage of the task it has completed; repeated calls to this method do not guarantee ascending values of percent.

The parent application will use this information submitted by the child process to present a percent completed progress bar to a user, for example. Some tasks may choose to go from 0 to 100 on all subtasks which are executed in order by a task. For example,

 m_taskMonitor.setPercentCompleted(0);
 m_taskMonitor.setStatus("fetching URL");
 // fetch URL
 m_taskMonitor.setPercentCompleted(100);
 m_taskMonitor.setPercentCompleted(0);
 m_taskMonitor.setStatus("parsing webpage");
 // parse webpage
 m_taskMonitor.setPercentCompleted(100);
 

This method should not block; it should return quickly.

Parameters:

percent - a value between 0 and 100 representing what [guessed] percentage of a task has completed; or -1 to indicate that a task is indeterminate.

Throws:

IllegalThreadStateException - TaskMonitor can only be be called from the thread that invokes the task run().

IllegalArgumentException -

if percent is not in the interval [-1, 100].

setEstimatedTimeRemaining

void setEstimatedTimeRemaining(long time)
                               throws IllegalThreadStateException

This is a hook for a child process to report to its parent application estimated time until task completion.

This hook is primarily useful for very long-running processes. For example, if a user initiates 100 queries to a database, it may be useful to report back to the user that the task will not complete for 5 minutes and 25 seconds.

Tasks are not required to report estimated time remaining. If a task does not to report this value, or has no way of determining it, the task can safely choose not to invoke this method.

Parameters:

time - estimated time until task completion, in milliseconds.

Throws:

IllegalThreadStateException - TaskMonitor can only be be called from the thread that invokes the task run().

setException

void setException(Throwable t,
                  String userErrorMessage)
                  throws IllegalThreadStateException

Indicates to a parent application that a task has encountered an error while processing.

This method provides a convenient mechanism for reporting errors back to the end-user.

This method is used to report non-recoverable fatal errors, and must be called at the very end of a run() method (for example, in a catch block).

Parameters:

t - an exception that occurred while processing of the task.

userErrorMessage - a user-presentable error message describing the nature of the exception; may be null.

Throws:

IllegalThreadStateException - TaskMonitor can only be be called from the thread that invokes the task run().

setException

void setException(Throwable t,
                  String userErrorMessage,
                  String recoveryTip)
                  throws IllegalThreadStateException

Indicates to a parent application that a task has encountered an error while processing.

This method provides a convenient mechanism for reporting errors back to the end-user.

This method is used to report non-recoverable fatal errors, and must be called at the very end of a run() method (for example, in a catch block).

Parameters:

t - an exception that occurred while processing of the task.

userErrorMessage - a user-presentable error message describing the nature of the exception; may be null.

recoveryTip - a use-presentable tip on how to recover from the error.

Throws:

IllegalThreadStateException - TaskMonitor can only be be called from the thread that invokes the task run().

setStatus

void setStatus(String message)
               throws IllegalThreadStateException,
                      NullPointerException

This is a hook for a child process to report to its parent application a short one-line text description (not exceeding, say, 60 characters, even though that is not enforced) of the current phase of processing.

For example, a spring embedded layout algorithm on a graph, if it were a task, could report a status string such as "Calculating node distances" and could later report a status string as "Calculating partial derivatives".

Parameters:

message - a non-null status message that describes the current state of a task's processing; use the empty string ("") to unset the current status message.

Throws:

NullPointerException - if message is null.

IllegalThreadStateException - TaskMonitor can only be be called from the thread that invokes the task run().