Package com.exedio.cope.util

Interface JobContext

All Known Implementing Classes:
AssertionErrorJobContext, EmptyJobContext, ProxyJobContext
public interface JobContext
An interface for controlling long-running jobs. Instances of this interface are not required to work for multiple threads accessing the methods concurrently. This interface has been inspired by TaskExecutionContext of cron4j.

  • Method Details

    • stopIfRequested

      void stopIfRequested() throws JobStop
      Checks, whether the job has been requested to stop. The job should call this method in reasonably short intervals. If throws a JobStop, the job should stop gracefully as soon as possible, but all resources held should be released.

      The job may call deferOrStopIfRequested(JobContext) instead.

      Throws:
      JobStop

    • requestsDeferral

      default Duration requestsDeferral()
      Returns the duration the job has been requested to defer by its context. This method is considered by deferOrStopIfRequested.

      In general the job should not call this method, but deferOrStopIfRequested.

      The default implementation returns zero.

    • deferOrStopIfRequested

      static void deferOrStopIfRequested(JobContext ctx) throws JobStop
      Defers the job, if the job is requested to defer by context ctx. The job should call this method in reasonably short intervals. The job should expect deferOrStopIfRequested to block for an unspecified amount of time. The job should not call deferOrStopIfRequested while holding valuable resources, in particular locks.

      Additionally checks, whether the job has been requested to stop or becomes requested to stop while deferring and throws a JobStop in such cases. Therefore, by calling deferOrStopIfRequested the job fulfills its obligation to call stopIfRequested().

      This method calls sleepAndStopIfRequested(Duration) for actually sleeping.

      Throws:
      JobStop

    • sleepAndStopIfRequested

      default void sleepAndStopIfRequested(Duration duration) throws JobStop
      Sleeps for the specified duration. In contrast to deferOrStopIfRequested(JobContext) this method actually waits for the specified amount of time. In contrast to Thread.sleep it aborts prematurely by throwing a JobStop, if the the job has been requested to stop or becomes requested to stop while sleeping.

      In general the job should not call this method directly, but only sleepAndStopIfRequested(JobContext, Duration). Override this method for affecting (potentially long) sleeps. For instance the job might temporarily release resources.

      Calling this method with duration zero or negative is equivalent to a call to stopIfRequested().

      The default implementation polls stopIfRequested() every 100 milliseconds. Implementers are encouraged to provide a more efficient implementation. The default implementation fails for durations too large for Duration.toNanos(), which is approximately 292 years.

      Throws:
      JobStop

    • sleepAndStopIfRequested

      static void sleepAndStopIfRequested(JobContext ctx, Duration duration) throws JobStop
      Sleeps for the specified duration. In contrast to deferOrStopIfRequested(JobContext) this method actually waits for the specified amount of time. In contrast to Thread.sleep it aborts prematurely by throwing a JobStop, if the the job has been requested to stop or becomes requested to stop while sleeping.

      The job may call this method, if the job itself (and not it context) requires some time to elapse. I contrast to stopIfRequested() and deferOrStopIfRequested(JobContext) there is no obligation to call this method in reasonably short intervals.

      Calling this method with duration zero or negative is equivalent to a call to stopIfRequested().

      This method calls sleepAndStopIfRequested(Duration) for actually sleeping.

      Throws:
      JobStop

    • supportsMessage

      boolean supportsMessage()
      Returns whether this context can process information transferred by setMessage(String).

    • setMessage

      void setMessage(String message)
      Indicates a message describing the current status of the job. Should be called only, if supportsMessage() returns true. Otherwise calls are ignored.

    • supportsProgress

      boolean supportsProgress()
      Returns whether this context can process information transferred by incrementProgress() and incrementProgress(int).

    • incrementProgress

      void incrementProgress()
      Indicates, that the job has proceeded. There is no information available, when the job will return. Calling this method is equivalent to calling incrementProgress(1). Should be called only, if supportsProgress() returns true. Otherwise calls are ignored.

    • incrementProgress

      void incrementProgress(int delta)
      Indicates, that the job has proceeded. There is no information available, when the job will return. Calling this method is equivalent to calling incrementProgress() for the number of delta times. Parameter delta should be greater or equal 0. Values out of range are accepted as well, thus no exception is thrown in that case. Calling this method with delta of 0 is equivalent to not calling this method at all. Should be called only, if supportsProgress() returns true. Otherwise calls are ignored.

    • supportsCompleteness

      boolean supportsCompleteness()
      Returns whether this context can process information transferred by setCompleteness(double).

    • setCompleteness

      void setCompleteness(double completeness)
      Indicates the current completeness of the job. Parameter completeness should be between 0 and 1. Values out of range are accepted as well, thus no exception is thrown in that case. Should be called only, if supportsCompleteness() returns true. Otherwise calls are ignored.