com.atlassian.scheduler.core

Class DelegatingSchedulerService

java.lang.Object

com.atlassian.scheduler.core.DelegatingSchedulerService

All Implemented Interfaces:

SchedulerService

Direct Known Subclasses:

TenantAwareSchedulerService

public class DelegatingSchedulerService
extends Object
implements SchedulerService

A scheduler service that delegates all requests to another scheduler service. The intended purpose is to allow applications to instantiate one of the AbstractSchedulerService implementations as a LifecycleAwareSchedulerService visible only to the application and register this restricted implementation as the SchedulerService that is available to add-ons.

Since:

v1.0

Constructor Summary

Constructors

Constructor and Description
DelegatingSchedulerService(SchedulerService delegate)

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DelegatingSchedulerService

public DelegatingSchedulerService(SchedulerService delegate)

Method Detail

registerJobRunner

public void registerJobRunner(JobRunnerKey jobRunnerKey,
                              JobRunner jobRunner)

Description copied from interface: SchedulerService

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.

Specified by:

registerJobRunner in interface SchedulerService

Parameters:

jobRunnerKey - Globally unique job runner key.

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

unregisterJobRunner

public void unregisterJobRunner(JobRunnerKey jobRunnerKey)

Description copied from interface: SchedulerService

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.

Specified by:

unregisterJobRunner in interface SchedulerService

Parameters:

jobRunnerKey - Globally unique job runner key.

getRegisteredJobRunnerKeys

@Nonnull
public Set<JobRunnerKey> getRegisteredJobRunnerKeys()

Description copied from interface: SchedulerService

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.

Specified by:

getRegisteredJobRunnerKeys in interface SchedulerService

Returns:

an immutable set containing all of the registered job runner keys

See Also:

SchedulerService.getJobRunnerKeysForAllScheduledJobs()

getJobRunnerKeysForAllScheduledJobs

@Nonnull
public Set<JobRunnerKey> getJobRunnerKeysForAllScheduledJobs()

Description copied from interface: SchedulerService

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.

Specified by:

getJobRunnerKeysForAllScheduledJobs in interface SchedulerService

Returns:

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

See Also:

SchedulerService.getRegisteredJobRunnerKeys()

scheduleJob

public void scheduleJob(JobId jobId,
                        JobConfig jobConfig)
                 throws SchedulerServiceException

Description copied from interface: SchedulerService

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

Specified by:

scheduleJob in interface SchedulerService

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
public JobId scheduleJobWithGeneratedId(JobConfig jobConfig)
                                          throws SchedulerServiceException

Description copied from interface: SchedulerService

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.

Specified by:

scheduleJobWithGeneratedId in interface SchedulerService

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

public void unscheduleJob(JobId jobId)

Description copied from interface: SchedulerService

Unschedules a previously scheduled job ID.

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

Specified by:

unscheduleJob in interface SchedulerService

Parameters:

jobId - the Job ID to be unregistered

calculateNextRunTime

@Nullable
public Date calculateNextRunTime(Schedule schedule)
                                    throws SchedulerServiceException

Description copied from interface: SchedulerService

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.

Specified by:

calculateNextRunTime in interface SchedulerService

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.

getJobDetails

@CheckForNull
public JobDetails getJobDetails(JobId jobId)

Description copied from interface: SchedulerService

Retrieves the details for the specified job ID.

Specified by:

getJobDetails in interface SchedulerService

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
public List<JobDetails> getJobsByJobRunnerKey(JobRunnerKey jobRunnerKey)

Description copied from interface: SchedulerService

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

Specified by:

getJobsByJobRunnerKey in interface SchedulerService

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