Package org.evolvis.tartools.backgroundjobs

Interface BackgroundJob<V>

Type Parameters:
V -
All Known Subinterfaces:
BackgroundJobWithProperties<V>
All Known Implementing Classes:
CompositeBackgroundJob, WeightedBackgroundJob
public interface BackgroundJob<V>
A unit of work that may be processed asynchronously. An instance of this class represents a potentially long-running task that may be scheduled and processed asynchronously by a BackgroundJobScheduler. This interface models the “inside” part of the contract that is to be fulfilled by the code implementing a particular job. To schedule a job, use BackgroundJobScheduler.schedule(BackgroundJob) or BackgroundJobScheduler.schedule(String, BackgroundJob). See also: BackgroundJobInfo, BackgroundJobScheduler, BackgroundJobStatus
Author:
lukas

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    getDescription()
    Describe the job.
    default boolean
    isCancellationSupported()
    Whether this job can be canceled.

    While most jobs should allow cancellation by the user, there will be cases where it is just not feasible or even dangerous to abort a job once it is running (i.e.
    default boolean
    isVisible()
    Whether this job should be visible to the end user.
    V
    work(BackgroundJobMonitor monitor)
    Execute the Job.

  • Method Details

    • work

      V work(BackgroundJobMonitor monitor) throws Exception
      Execute the Job. This method is typically called by some sort of scheduler. This method should never be called twice on the same instance! While executing, implementations should use the BackgroundJobMonitor to communicate with the scheduler:
      Parameters:
      monitor - The job monitor that should be used to communicate with the scheduler.
      Returns:
      the result produced by this job. Schedulers should ignore the returned value if the job has been aborted before finishing normally.
      Throws:
      Exception - The scheduler should be prepared to deal with any kind of exception by marking the job as failed.

    • getDescription

      String getDescription()
      Describe the job.
      Returns:
      a human-readable Description of the job.

    • isCancellationSupported

      default boolean isCancellationSupported()
      Whether this job can be canceled.

      While most jobs should allow cancellation by the user, there will be cases where it is just not feasible or even dangerous to abort a job once it is running (i.e. once the work(BackgroundJobMonitor) method is executing). Those jobs usually simply ignore the value of BackgroundJobMonitor.isAborting() and just keep on running until they are done.
      If a job just cannot be cancelled, the UI should communicate this fact to the user (e.g. by not showing a Cancel-Button in the first place). Implementations should override this method and return false.
      NOTE: While in state BackgroundJobInfo.State.SCHEDULED, a job can always be canceled, regardless of what this method returns.
      Returns:
      a boolean indicating whether this job can be canceled once its execution has started.
      Since:
      1.21

    • isVisible

      default boolean isVisible()
      Whether this job should be visible to the end user.

      In applications that provide some kind of manegment UI for scheduled/running jobs it might make sense to hide certain jobs from the user. Examples would be jobs that are started automatically, have a very short runtime and are not intended to be interacted with in any way.

      Implementation can override this method and return false to indicate that this job should not be shown in the UI.
      Returns:
      a boolean indicating whether this job should be visible to the end user.
      Since:
      1.21