- All Known Subinterfaces:
@Beta @PublicAPI public interface ProgressObserver extends CancelObserver, AutoCloseableObserver 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:
IProgressMonitorAPI: 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 however it is a not recommended practice.
- 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.
- Work reporting method
worked(long)is expected to be invoked with an approximately constant frequency. This allows the implementation of efficient update filtering.
- Frequent invocation of
worked(long)is considered a normal practice.
- Sub observers are not expected to be mass created by
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.
- An observer is expected to report all work units either by method
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.
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description
done()Notifies that the represented task is done and no further work will be done.
subTask(String name, long work)Deprecated.Will be removed.
switchToDeterminate(long totalWork)Notifies that the remaining amount of work units to complete this task is known.
worked(long work)Notifies that a given number of work units has been completed.
workUnit(String workUnit)Notifies the measure unit of work (such as 'pc', 'file', 'percent', etc).
void switchToDeterminate(long totalWork)Notifies that the remaining amount of work units to complete this task is known. (Calling this method is not mandatory.)
void workUnit(String workUnit)Notifies the measure unit of work (such as 'pc', 'file', 'percent', etc). (Calling this method is not mandatory.)
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.
void done()Notifies that the represented task is done and no further work will be done. Additional calls to this method cause no effect. (idempotency)
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()Equivalent to
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(String name, long work)Deprecated.Will be removed.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
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.
- An unitialized observer to be used by a subtask. The returned observer will reflect the same cancelling behavior as the current one.
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