@Beta @PublicAPI public interface ProgressObserver extends CancelObserver
The semantics of this observer is influenced by the progress reporting facility of the Eclipse Platform; for details
org.eclipse.core.runtime.IProgressMonitor, associated classes/interfaces and documentations:
IProgressMonitorAPI: http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.do c.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcore%2Fruntime%2FIProgressMonitor.html
Design aspects of this progress observing facility:
worked(long)is expected to be invoked with an approximately constant frequency. This allows the implementation of efficient update filtering.
worked(long)is considered a normal practice.
subTask(java.lang.String, long). Total number of created sub observers is expected to remain under a few 10s at most. Also it is not expected to create deeply nested sub observer hierarchy.
worked(long)or by using sub observers. Mixed reporting is valid but non recommended.
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.
|Modifier and Type||Method and Description|
Follow the processing of a specific amount of work units by a separate observer.
Notifies that the remaining amount of work units to complete this task is known.
Notifies that a given number of work units has been completed.
void switchToDeterminate(long totalWork)
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
totalWork- The total amount of work represented by this task.
java.lang.IllegalStateException- When this method already called
totalWorkis zero or negative
void worked(long work)
Note that this amount represents an installment, as opposed to a cumulative amount of work done to date.
work- Amount of work reported
java.lang.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.
workis zero or negative
SubProgressObserver subTask(java.lang.String name, long work)
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.
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.
java.lang.IllegalStateException- When the total amount of work known (
switchToDeterminate(long)and already logged (or expected to be logged) amount exceeds it.
workis zero or negative