Package com.chemaxon.calculations.common

Interface ProgressObserver

All Superinterfaces:
AutoCloseable, CancelObserver
All Known Subinterfaces:
SubProgressObserver
@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:

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

    Modifier and Type
    Method
    Description
    default void
    close()
    Equivalent to done().
    void
    done()
    Notifies that the represented task is done and no further work will be done.
    ProgressObserver
    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 Details

    • 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 ProgressObserver 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