com.atlassian.scheduler.core

Class AbstractSchedulerService

java.lang.Object

com.atlassian.scheduler.core.AbstractSchedulerService

All Implemented Interfaces:

LifecycleAwareSchedulerService, SchedulerServiceController, SchedulerService

Direct Known Subclasses:

Quartz1SchedulerService, Quartz2SchedulerService

public abstract class AbstractSchedulerService
extends Object
implements LifecycleAwareSchedulerService

Base class for implementing a scheduler service. Provides JobRunner registration, and job status tracking.

Since:

v1.0

Nested Class Summary

Nested classes/interfaces inherited from interface com.atlassian.scheduler.core.LifecycleAwareSchedulerService

LifecycleAwareSchedulerService.State

Field Summary

Fields

Modifier and Type	Field and Description
protected static Comparator<JobDetails>	BY_JOB_ID Sorts by job ID (and nothing else).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractSchedulerService(RunDetailsDao runDetailsDao)
protected	AbstractSchedulerService(RunDetailsDao runDetailsDao, ParameterMapSerializer parameterMapSerializer)

Method Summary

Modifier and Type	Method and Description
RunDetails	addRunDetails(JobId jobId, Date startedAt, RunOutcome runOutcome, String message) Creates or updates the job status record for the given job ID.
protected static SchedulerServiceException	checked(SchedulerRuntimeException sre) Converts the unchecked SchedulerRuntimeException to the checked SchedulerServiceException.
JobRunner	getJobRunner(JobRunnerKey jobRunnerKey)
Collection<RunningJob>	getLocallyRunningJobs() Returns the list of jobs that are currently executing on this node.
ParameterMapSerializer	getParameterMapSerializer() Returns the parameter map serializer used by this scheduler.
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.
LifecycleAwareSchedulerService.State	getState() Returns the scheduler service's running state.
void	postJob() This method is called after a job has finished execution.
void	preJob() This method is called before a job begins execution.
void	registerJobRunner(JobRunnerKey jobRunnerKey, JobRunner jobRunner) Registers the job runner for a given job runner key.
JobId	scheduleJobWithGeneratedId(JobConfig jobConfig) Schedules a "dynamic" job by generating a new unique job ID.
void	shutdown() Permanent shutdown of the scheduler.
protected abstract void	shutdownImpl() Provided by the scheduler service to implement shutdown() requests.
void	standby() Places the scheduler into standby mode.
protected abstract void	standbyImpl() Provided by the scheduler service to implement standby() requests.
void	start() Starts the scheduler if it had never been started or had been placed in SchedulerServiceController.standby() mode.
protected abstract void	startImpl() Provided by the scheduler service to implement start() requests.
void	unregisterJobRunner(JobRunnerKey jobRunnerKey) Unregisters the specified job runner.
boolean	waitUntilIdle(long timeout, TimeUnit units) Waits for up to timeout units for any currently executing jobs to complete.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.atlassian.scheduler.SchedulerService

calculateNextRunTime, getJobDetails, getJobRunnerKeysForAllScheduledJobs, getJobsByJobRunnerKey, scheduleJob, unscheduleJob

Field Detail

BY_JOB_ID

protected static final Comparator<JobDetails> BY_JOB_ID

Sorts by job ID (and nothing else). This is useful for implementing SchedulerService.getJobsByJobRunnerKey(JobRunnerKey).

Constructor Detail

AbstractSchedulerService

protected AbstractSchedulerService(RunDetailsDao runDetailsDao)

AbstractSchedulerService

protected AbstractSchedulerService(RunDetailsDao runDetailsDao,
                                   ParameterMapSerializer parameterMapSerializer)

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.

getJobRunner

public JobRunner getJobRunner(JobRunnerKey jobRunnerKey)

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

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

addRunDetails

public RunDetails addRunDetails(JobId jobId,
                                Date startedAt,
                                RunOutcome runOutcome,
                                @Nullable
                                String message)

Creates or updates the job status record for the given job ID.

Parameters:

jobId - the job ID for which the status is being updated

startedAt - the clock time that the run started at

runOutcome - the result of the run

message - an optional informational message to include in the RunDetails

Returns:

the newly created run details.

preJob

public void preJob()

This method is called before a job begins execution.

postJob

public void postJob()

This method is called after a job has finished execution.

start

public final void start()
                 throws SchedulerServiceException

Description copied from interface: SchedulerServiceController

Starts the scheduler if it had never been started or had been placed in SchedulerServiceController.standby() mode. If the scheduler was already active, then the request has no effect.

Specified by:

start in interface SchedulerServiceController

Throws:

SchedulerServiceException - if the scheduler cannot be started

standby

public final void standby()
                   throws SchedulerServiceException

Description copied from interface: SchedulerServiceController

Places the scheduler into standby mode. This stops jobs from running until it is started again. If the scheduler was already in standby, then the request has no effect. The standby mode only affects the local node's ability to schedule jobs. For any RunMode.RUN_ONCE_PER_CLUSTER jobs the jobs may still run on other nodes if they exist and have started. If a job should have run while the scheduler was in standby mode, the implementation may trigger those jobs when restarted, but this is not guaranteed.

Specified by:

standby in interface SchedulerServiceController

Throws:

SchedulerServiceException - if the scheduler cannot be be placed in standby mode

shutdown

public final void shutdown()

Description copied from interface: SchedulerServiceController

Permanent shutdown of the scheduler. Once this has been called, no more jobs will be run and most requests will fail. The scheduler cannot be restarted once it has been shut down.

Specified by:

shutdown in interface SchedulerServiceController

waitUntilIdle

public boolean waitUntilIdle(long timeout,
                             TimeUnit units)
                      throws InterruptedException

Waits for up to timeout units for any currently executing jobs to complete. Note that if the scheduler has not been SchedulerServiceController.shutdown() or placed in SchedulerServiceController.standby() mode, then jobs could start after this returns true. As with SchedulerServiceController.getLocallyRunningJobs(), this is only aware of jobs running on this node of the cluster, and it is guaranteed to be safe to call even after a SchedulerServiceController.shutdown().

Implementations may override the default implementation for waitUntilIdle. The default implementation that AbstractSchedulerService provides will poll getLocallyRunningJobs() every 100ms until one of the following occurs:

1. getLocallyRunningJobs() returns an empty collection.
2. The current thread is interrupted.
3. The timeout is exhausted.

Specified by:

waitUntilIdle in interface SchedulerServiceController

Parameters:

timeout - the timeout period, in the specified units; non-positive values request an immediate poll — that is, it is equivalent to getLocallyRunningJobs().isEmpty()

Returns:

true if the scheduler is now idle; false if jobs are still executing.

Throws:

InterruptedException - if the current thread is interrupted while waiting for the scheduler to become idle.

getLocallyRunningJobs

@Nonnull
public Collection<RunningJob> getLocallyRunningJobs()

Description copied from interface: SchedulerServiceController

Returns the list of jobs that are currently executing on this node. In a clustered configuration, this will not reflect any jobs that are running on another node of the cluster. This is guaranteed to be safe to call even after a SchedulerServiceController.shutdown().

Specified by:

getLocallyRunningJobs in interface SchedulerServiceController

Returns:

the job IDs for all jobs that are currently running on this node.

getState

@Nonnull
public final LifecycleAwareSchedulerService.State getState()

Description copied from interface: SchedulerServiceController

Returns the scheduler service's running state. The scheduler is initially in LifecycleAwareSchedulerService.State.STANDBY and can be moved between this state and LifecycleAwareSchedulerService.State.STANDBY freely. LifecycleAwareSchedulerService.State.SHUTDOWN is terminal — that is, once shut down, the scheduler's state can no longer be changed.

Specified by:

getState in interface SchedulerServiceController

Returns:

the scheduler service's running state.

startImpl

protected abstract void startImpl()
                           throws SchedulerServiceException

Provided by the scheduler service to implement start() requests. This is only ever called while in State#STANDBY, and throwing an exception will prevent the state from being updated.

Throws:

SchedulerServiceException - if the scheduler implementation fails to start

standbyImpl

protected abstract void standbyImpl()
                             throws SchedulerServiceException

Provided by the scheduler service to implement standby() requests. This is only ever called while in State#STARTED, and throwing an exception will prevent the state from being updated.

Throws:

SchedulerServiceException - if the scheduler implementation fails to enter standby mode

shutdownImpl

protected abstract void shutdownImpl()

Provided by the scheduler service to implement shutdown() requests. This is only ever called if the scheduler has not already been shut down, and throwing an exception does not prevent the scheduler service from entering this state.

getParameterMapSerializer

public ParameterMapSerializer getParameterMapSerializer()

Returns the parameter map serializer used by this scheduler.

Returns:

the parameter map serializer used by this scheduler.

checked

protected static SchedulerServiceException checked(SchedulerRuntimeException sre)

Converts the unchecked SchedulerRuntimeException to the checked SchedulerServiceException. It makes sense to do this in many cases where the checked exception is declared, as the caller is already having to handle it.

The message and cause of the SchedulerServiceException are taken from the cause of the runtime exception. If no cause was set, then the runtime exception itself is used.

Parameters:

sre - the scheduler runtime exception to convert

Returns:

the converted exception