Class JobScheduler


  • public abstract class JobScheduler
    extends Object
    Schedules background jobs, either at fixed rate or a fixed delay between executions.

    Jobs are created either with clusterJob(String) or localJob(String) and then scheduled to execute.

    Since:
    3.11.0
    • Constructor Detail

      • JobScheduler

        protected JobScheduler()
    • Method Detail

      • setInstance

        public static void setInstance​(JobScheduler instance)
        Changes the scheduler instance. The default scheduler is already cluster compatible. Applications may provide an alternate scheduler if they want to rely on a different job framework than the default.
        Parameters:
        instance - the new scheduler
      • clusterJob

        public final Job.Builder clusterJob​(String jobId)
        Creates a builder for a job that must run on only one node of the cluster each time that it triggers. Use localJob(String) if the job must run on each node of the cluster.

        Note a cluster job cannot use a fixed delay schedule.

        Parameters:
        jobId - the identifier of the job to create
        Returns:
        a job builder instance
        Throws:
        NullPointerException - if jobId is null or empty
      • localJob

        public final Job.Builder localJob​(String jobId)
        Creates builder for a job scheduled so that it will apply only to this particular node of the cluster. Use clusterJob(String) for a job that must run on only one node of the cluster each time that it triggers.
        Parameters:
        jobId - the identifier of the job to create
        Returns:
        a job builder instance
        Throws:
        NullPointerException - if jobId is null or empty
      • jobBuilder

        protected abstract Job.Builder jobBuilder()
        Creates a builder of job.
        Returns:
        a new builder instance
      • getJobs

        public Collection<Job> getJobs()
        Returns an unmodifiable collection of jobs built by this scheduler.
        Returns:
        the known jobs
      • getJob

        public Optional<Job> getJob​(String id)
        Returns the job of given identifier built by this scheduler, if any
        Parameters:
        id - the job identifier to look for
        Returns:
        the corresponding job, or an empty optional
      • schedule

        public final void schedule​(Job job,
                                   JobSchedule defaultSchedule)
                            throws JobSchedulerException
        Schedules the background job. This method is to call when a job is just created and is to schedule initially.

        The given schedule is used as a default. If an administrator has edited the schedule for this job, to use a more suitable time for triggering it, the default schedule is discarded and the edited one is applied.

        This method automatically cancels previous scheduling, if any. All jobs are also automatically unscheduled when the application is disposed.

        This method may also be used to disable job scheduling, so that the job no longer runs.

        Parameters:
        job - the job to schedule
        defaultSchedule - the default schedule to use
        Throws:
        NullPointerException - if job or defaultSchedule is null
        IllegalArgumentException - if it is a cluster job and a fixed delay schedule.
        JobSchedulerException - if anything prevents scheduling the job
      • getJobConfig

        public JobConfig getJobConfig​(Job job,
                                      List<Locale> locales)
        Returns a resource describing the configuration of the job.
        Parameters:
        locales - the locales to use, in decreasing order starting with the preferred locale.
        Returns:
        the job config resource
      • doSchedule

        protected abstract void doSchedule​(Job job)
                                    throws JobSchedulerException
        Performs the scheduling of the job. The job is known to be already unscheduled at this stage.
        Parameters:
        job - the job to schedule
        Throws:
        JobSchedulerException - if anything prevents scheduling the job
      • doUnschedule

        protected abstract void doUnschedule​(Job job)
                                      throws JobSchedulerException
        Performs the job unscheduling.
        Parameters:
        job - the job to unschedule
        Throws:
        JobSchedulerException - if anything prevents unscheduling the job
      • dispose

        protected void dispose()
        Disposes the resources used by this scheduler and unschedules all jobs.