com.chemaxon.calculations.common

Interface ProgressObserver

All Superinterfaces:

CancelObserver

All Known Subinterfaces:

SubProgressObserver

@Beta
public interface ProgressObserver
extends CancelObserver

Observer for reporting the progress of long running tasks.

The semantics of this observer is influenced by the progress reporting facility of the Eclipse Platform; for details see org.eclipse.core.runtime.IProgressMonitor, associated classes/interfaces and documentations:

• IProgressMonitor API: http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.do c.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcore%2Fruntime%2FIProgressMonitor.html
• Detailed description: http://www.eclipse.org/articles/Article-Progress-Monitors/article.html

Design aspects of this progress observing facility:

• The execution observed is divided into work units.
• The sum of the remaining work units needed to be processed up to the completion of the work can be known exactly prior execution, can become known during process or remain unknown.
• Some of the work units can be observed through a sub observer in a more detailed way. The total work units done on the upper level represented by the completion of the sub task must be specified,
• Work units/subtasks might be worked/completed asynchronously
• ProgressObservers also used for cancellation reporting. Since it is a cross cutting concern it is exposed as a separate but extended interface.
• ProgressObserver starts in an indefinite state and can transit to definite when the amount of remaining work became known. Transition back to indefinite state is not possible.
• Please note that certain implementations might not provide strict API contract enforcement; an implementation might not throw exception in case of inconsistent usage.

Thread safety: implementations are not required to be thread safe. Observed processes must be prepared for working with non thread safe observers. Consequently observer methods can be called only on the thread invoked the observed function. Alternatively proper synchronization must be ensured by the observed code.

Please note that this interface is marked with @Beta annotation, so it can be subject of incompatible changes or removal in any of the later releases.

Author:

Gabor Imre

Method Summary

Methods

Modifier and Type	Method and Description
SubProgressObserver	subTask(String name, long work) Follow the processing of a specific amount of work units by a separate observer.
void	switchToDeterminate(long totalWork) Notifies that the remaining amount of work units to complete this task is known.
void	worked(long work) Notifies that a given number of work units has been completed.

Methods inherited from interface com.chemaxon.calculations.common.CancelObserver

isCancelled

Method Detail

switchToDeterminate

void switchToDeterminate(long totalWork)

Notifies that the remaining amount of work units to complete this task is known.

Call this when the represented total work to be done is known or became known. It is valid to call this method after work units already reported in indeterminate mode

Parameters:

totalWork - The total amount of work represented by this task.

Throws:

IllegalStateException - When this method already called

IllegalArgumentException - When totalWork is zero or negative

worked

void worked(long work)

Notifies that a given number of work units has been completed.

Note that this amount represents an installment, as opposed to a cumulative amount of work done to date.

Parameters:

work - Amount of work reported

Throws:

IllegalStateException - When the total amount of work known and already logged (or expected to be logged) amount exceeds it. Also when no done() is already invoked or the observer is closed in other implementation specific way.

IllegalArgumentException - When work is zero or negative

subTask

SubProgressObserver subTask(String name,
                          long work)

Follow the processing of a specific amount of work units by a separate observer.

The given amount of work on the level of the current observer is considered completed upon SubProgressObserver.done() called on the returned subtask's observer.

Cancel propagation is expected to be transparent.

The strict contract regarding the state when worked(long) can be called is relaxed in the context of subtask observers: implicitly logging work on the upper level by calling SubProgressObserver.done() on the subtask level after the upper level is closed will no cause problem on either level.

Parameters:

name - Name of the represented sub task (for example to display)

work - A non-negative number of work units considered to be completed upon finishing the associated subtask.

Returns:

An unitialized observer to be used by a subtask. The returned observer will reflect the same cancelling behavior as the current one.

Throws:

IllegalStateException - When the total amount of work known (switchToDeterminate(long) and already logged (or expected to be logged) amount exceeds it.

IllegalArgumentException - When work is zero or negative