ProgressObserver (overlap-examples-cli-dist 0.3.5 API)

All Superinterfaces:

AutoCloseable, CancelObserver

All Known Subinterfaces:

SubProgressObserver

All Known Implementing Classes:

ConsolePO, ListenableObserver, NoOverflowAutoDoneProgressObserver, ObservableProgressObserver, SplitObserver, StatPO
```
@Beta
 @PublicAPI
public interface ProgressObserver
extends CancelObserver, AutoCloseable
```
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 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.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default void`	`close()` Equivalent to `done()`.
`void`	`done()` Notifies that the represented task is done and no further work will be done.
`SubProgressObserver`	`subTask(String name, long work)` Deprecated. Will be removed.
`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.
`void`	`workUnit(String workUnit)` Notifies the measure unit of work (such as 'pc', 'file', 'percent', etc).

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. (Calling this method is not mandatory.)
    
    Parameters:
    
    totalWork - The total amount of work represented by this task.
    
    Throws:
    
    IllegalStateException - When worked(long) or done() already called.
    
    IllegalArgumentException - When totalWork is zero or negative
  - workUnit
```
void workUnit(String workUnit)
```
    Notifies the measure unit of work (such as 'pc', 'file', 'percent', etc). (Calling this method is not mandatory.)
    
    Parameters:
    
    workUnit - the measure unit of work.
    
    Throws:
    
    IllegalStateException - When worked(long) or done() already called.
  - 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 accumulated work would exceed it.
    
    IllegalStateException - When done() is already invoked.
    
    IllegalArgumentException - When work is zero or negative
  - done
```
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
  - close
```
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.
    
    Specified by:
    
    close in interface AutoCloseable
  - subTask
```
@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.
    
    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

Interface ProgressObserver

Method Summary

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

Method Detail

switchToDeterminate

workUnit

worked

done

close

subTask