@Beta @PublicAPI public interface ProgressObserver extends CancelObserver, java.lang.AutoCloseable
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|
Notifies that the represented task is done and no further work will be done.
Will be removed.
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.
Notifies the measure unit of work (such as 'pc', 'file', 'percent', etc).
void switchToDeterminate(long totalWork)
void workUnit(java.lang.String workUnit)
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 accumulated work would exceed it.
done()is already invoked.
workis zero or negative
NOTE: Cancellation has no effect to the progress state, so this method must be invoked when done, either due normal completion; cancellation or error
default void close()
done(). This method is here just to be compatible with
AutoCloseable. Default implementation delegates call to
done(). Overriding this default method is not recommended.
@Deprecated SubProgressObserver subTask(java.lang.String name, long work)
The given amount of work on the level of the current observer is considered completed upon
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
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