Package chemaxon.clustering.common

Interface ProgressObserver

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
PhasedProgressObserver
@Beta @PublicApi public interface ProgressObserver extends AutoCloseable
Observer for reporting the progress of long-running tasks.

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.
  • Work units/subtasks might be worked/completed asynchronously however it is a not recommended practice.
  • Observers are also used for cancellation reporting. Since it is a cross-cutting concern, it is exposed as a separate, but extended interface.
  • An observer starts in an indefinite state and can transit to definite when the amount of remaining work becomes 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.

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 that invoked the observed function. Alternatively, proper synchronization must be ensured by the observed code.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Notifies that the represented task has completed (either successfully or because of a failure), and no further work will be done.
    boolean
    isCancelled()
    Returns whether cancellation of current task has been requested.
    static ProgressObserver
    nullObserver()
    Returns an observer that ignores progress report and cannot be cancelled.
    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.

  • Method Details

    • nullObserver

      static ProgressObserver nullObserver()
      Returns an observer that ignores progress report and cannot be cancelled.
      Returns:
      a null observer

    • 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 close() already called.
      IllegalArgumentException - When totalWork is zero or negative

    • 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

    • close

      void close()
      Notifies that the represented task has completed (either successfully or because of a failure), and no further work will be done.

      Repeated calls to this method has no effect (idempotency).

      Specified by:
      close in interface AutoCloseable

    • isCancelled

      boolean isCancelled()
      Returns whether cancellation of current task has been requested.

      Long running/memory intensive operations should poll to see if cancellation has been requested. Since time-out based cancellations might be implemented polling should not be done too often.

      It is expected that implementations won't return false after a true value returned. It is also expected that implementations tolerate multiple calls regardless of the cancellation state.

      Returns:
      true if cancellation has been requested, false otherwise