jklustor-all-api-0.0.7-20140619012755 (ChemAxon)


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:

Design aspects of this progress observing facility:

Thread safety: an instance is not guaranteed to be thread safe.

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

Author:
Gabor Imre

Field Summary
 
Fields inherited from interface com.chemaxon.calculations.common.CancelObserver
FIRED_PROPERTY_NAME
 
Method Summary
 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
addPropertyChangeListener, isCancelled, removePropertyChangeListener
 

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

jklustor-all-api-0.0.7-20140619012755 (ChemAxon)