com.atlassian.scheduler

Interface SchedulerService

@PublicApi
public interface SchedulerService

Scheduler service for Atlassian products and their plugins.

This service provides the ability to schedule services for execution, either as a one time task, as a repeating task, or according to a formal cron-style schedule.

Applications and add-ons define the scheduled work to perform by registering a JobRunner with a unique key. The scheduled work is performed according to individual scheduled jobs that the define its configuration, including when it should run and any parameters that the job runner needs to know The work to be performed is registered as a JobRunner, and the schedule and associated data are set by scheduling a specific job for that runner. Multiple jobs can be scheduled for a given job runner.

Method Summary

Modifier and Type	Method and Description
Date	calculateNextRunTime(Schedule schedule) Returns the next time that a job with the given schedule would be expected to run.
JobDetails	getJobDetails(JobId jobId) Retrieves the details for the specified job ID.
Set<JobRunnerKey>	getJobRunnerKeysForAllScheduledJobs() Returns all of the job runner keys that have been used to schedule jobs, regardless of whether or not JobRunners are currently registered for them.
List<JobDetails>	getJobsByJobRunnerKey(JobRunnerKey jobRunnerKey) Retrieves the job details for all jobs with the given job runner key.
Set<JobRunnerKey>	getRegisteredJobRunnerKeys() Returns all of the job runner keys that currently have registered job runners, regardless of whether or not any jobs have actually been scheduled for them.
void	registerJobRunner(JobRunnerKey jobRunnerKey, JobRunner jobRunner) Registers the job runner for a given job runner key.
void	scheduleJob(JobId jobId, JobConfig jobConfig) Schedules a job with the given job ID.
JobId	scheduleJobWithGeneratedId(JobConfig jobConfig) Schedules a "dynamic" job by generating a new unique job ID.
void	unregisterJobRunner(JobRunnerKey jobRunnerKey) Unregisters the specified job runner.
void	unscheduleJob(JobId jobId) Unschedules a previously scheduled job ID.

Method Detail

registerJobRunner

void registerJobRunner(JobRunnerKey jobRunnerKey,
                       JobRunner jobRunner)

Registers the job runner for a given job runner key. Registration does not survive application restart, and must be done on each node for clustered applications. A second registration with the same jobRunnerKey will replace any existing registration.

A job that is scheduled to run but has no registered job runner is reported as unavailable.

Parameters:

jobRunnerKey - Globally unique job runner key.

jobRunner - the concrete object capable of running instances of this job

unregisterJobRunner

void unregisterJobRunner(JobRunnerKey jobRunnerKey)

Unregisters the specified job runner. Plugins should unregister their job runners as part of being disabled.

Jobs that fire with no registered job runner will fail to start.

Parameters:

jobRunnerKey - Globally unique job runner key.

getRegisteredJobRunnerKeys

@Nonnull
Set<JobRunnerKey> getRegisteredJobRunnerKeys()

Returns all of the job runner keys that currently have registered job runners, regardless of whether or not any jobs have actually been scheduled for them. The job runner keys are not guaranteed to be returned in any particular order.

Returns:

an immutable set containing all of the registered job runner keys

See Also:

getJobRunnerKeysForAllScheduledJobs()

getJobRunnerKeysForAllScheduledJobs

@Nonnull
Set<JobRunnerKey> getJobRunnerKeysForAllScheduledJobs()

Returns all of the job runner keys that have been used to schedule jobs, regardless of whether or not JobRunners are currently registered for them. The job runner keys are not guaranteed to be returned in any particular order.

Returns:

an immutable set containing all of the job runner keys with scheduled jobs

See Also:

getRegisteredJobRunnerKeys()

scheduleJob

void scheduleJob(JobId jobId,
                 JobConfig jobConfig)
          throws SchedulerServiceException

Schedules a job with the given job ID.

If a job already exists with the given ID, then it will be replaced with the new run config. If the schedule is eligible to run immediately and multiple nodes take this action at close to the same time, then the job might run more than once as the instances replace one another.

In most cases, this will be harmless, but it can be avoided by making sure the job will not be eligible to run until some time in the future. For example, when using an interval schedule, the caller can first check whether or not the job already exists, and if it does not then specify an initial start date for the schedule, as in:

     Schedule.forInterval(120000L, new Date(System.currentTimeMillis() + 15000L))
 

Since the schedule will not be eligible to run until 15 seconds after the current time, any race conditions between two nodes starting up at once and trying to schedule the same job should resolve before the job actually fires. For cron expressions, this is a little bit more difficult, but you can set the seconds field to an explicit value to accomplish the same thing. For example:

     final Calendar calendar = new GregorianCalendar();
     calendar.add(15, Calendar.SECOND);
     final Schedule schedule = Schedule.forCronExpression(
             calendar.get(Calendar.SECOND) + " 0 2 * * ?");  // at or just after 2 A.M.
     scheduleJob(...
 

Parameters:

jobId - the Job ID

jobConfig - the configuration details for the job instance including schedule, run mode, run parameters, etc.

Throws:

SchedulerServiceException - if the job cannot be scheduled because there is a problem with either the provided configuration or within the scheduler implementation itself

scheduleJobWithGeneratedId

@Nonnull
JobId scheduleJobWithGeneratedId(JobConfig jobConfig)
                                   throws SchedulerServiceException

Schedules a "dynamic" job by generating a new unique job ID.

This method should normally only be used when creating multiple jobs for a given job runner key that need to run independently — most likely because these are created in response to user input.

Parameters:

jobConfig - the configuration details for the job instance including schedule, run mode, run parameters, etc.

Returns:

the generated unique Job ID

Throws:

SchedulerServiceException - if the job cannot be scheduled because there is a problem with either the provided configuration or within the scheduler implementation itself

unscheduleJob

void unscheduleJob(JobId jobId)

Unschedules a previously scheduled job ID.

If no such job exists, then the request is ignored.

Parameters:

jobId - the Job ID to be unregistered

calculateNextRunTime

@Nullable
Date calculateNextRunTime(Schedule schedule)
                             throws SchedulerServiceException

Returns the next time that a job with the given schedule would be expected to run.

Caveats:

• Interval schedules taken from JobDetails are not aware of the job that they came from or whether or not that job has previously run. They are calculated on the basis of the current time, not the original job's history.
• Schedules based on cron expressions are implicitly validated by this request.
• The initial run time reported is not a strong guarantee. The actual initial run time that is calculated by the schedule may depend on the exact time that the schedule is created. The return value should be treated as an estimate, only.

Parameters:

schedule - the schedule to evaluate

Returns:

the estimated time that the schedule would next run, or null if it would never run

Throws:

SchedulerServiceException - if schedule is invalid.

Since:

v1.6.0

getJobDetails

@CheckForNull
JobDetails getJobDetails(JobId jobId)

Retrieves the details for the specified job ID.

Parameters:

jobId - the Job ID for which to retrieve the details

Returns:

the job details, or null if no such job is defined

getJobsByJobRunnerKey

@Nonnull
List<JobDetails> getJobsByJobRunnerKey(JobRunnerKey jobRunnerKey)

Retrieves the job details for all jobs with the given job runner key.

Parameters:

jobRunnerKey - the job runner key to look up

Returns:

the jobs that are registered with the given job runner key, or an empty collection if there are no jobs that use the given key; never null