Package chemaxon.util.progress

Interface ProgressObserver

All Superinterfaces:
AutoCloseable
@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.
    default void
    done()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Implement close() instead, and create instances of this interface in a try-with-resources block.
    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.
    default ProgressObserver
    subTask(String name, long work)
    Deprecated, for removal: This API element is subject to removal in a future version.
    No longer used, 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.
    default void
    workUnit(String workUnit)
    Deprecated, for removal: This API element is subject to removal in a future version.
    No longer used, will be removed.

  • 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

    • workUnit

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) default void workUnit(String workUnit)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No longer used, will be removed.
      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 close() 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

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) default void done()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Implement close() instead, and create instances of this interface in a try-with-resources block.
      Notifies that the represented task is done and no further work will be done.

      Additional calls to this method cause no effect. (idempotency)

    • 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

    • subTask

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) default ProgressObserver subTask(String name, long work)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No longer used, 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 close() 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 close() 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

    • 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