Package com.exedio.cope.util

Interface JobContext

    • Method Detail

      • 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

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

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