com.atlassian.scheduler.caesium.spi

Interface ClusteredJobDao

All Known Implementing Classes:

MemoryClusteredJobDao

public interface ClusteredJobDao

The host application SPI for persisting clustered jobs.

Although additional requirements may be specified on individual methods, implementations:

• MUST ensure that JobId is constrained as UNIQUE.
• MUST preserve the clustered job information across system restarts.
• SHOULD query the least amount of information as is possible to satisfy the request

Since:

v0.0.1

Method Summary

Modifier and Type	Method and Description
boolean	create(ClusteredJob clusteredJob) Called to create a new clustered job in the database.
boolean	delete(com.atlassian.scheduler.config.JobId jobId) Called to remove a scheduled cluster job by its ID.
ClusteredJob	find(com.atlassian.scheduler.config.JobId jobId) Finds and returns the persisted details for a clustered job.
Set<com.atlassian.scheduler.config.JobRunnerKey>	findAllJobRunnerKeys() Returns the set of distinct job runner keys that have at least one job schedule stored here.
Collection<ClusteredJob>	findByJobRunnerKey(com.atlassian.scheduler.config.JobRunnerKey jobRunnerKey) Returns all jobs that use the given job runner.
Date	getNextRunTime(com.atlassian.scheduler.config.JobId jobId) Returns the next run time for the given job ID, if there is one.
Long	getVersion(com.atlassian.scheduler.config.JobId jobId) Returns the current version of the persisted clustered job with this ID.
Map<com.atlassian.scheduler.config.JobId,Date>	refresh() Returns the job ID and next run time for every clustered job that should be in the queue.
boolean	updateNextRunTime(com.atlassian.scheduler.config.JobId jobId, Date nextRunTime, long expectedVersion) Updates the next run time for an existing clustered job.

Method Detail

getNextRunTime

@Nullable
Date getNextRunTime(com.atlassian.scheduler.config.JobId jobId)

Returns the next run time for the given job ID, if there is one.

Implementations MAY implement this with:

     ClusteredJob clusteredJob = find(jobId);
     return (clusteredJob != null) ? clusteredJob.getNextRunTime() : null;
 

However, this would be wasteful, and implementations SHOULD use a more efficient query when possible.

Parameters:

jobId - the job ID whose existence and current version is to be checked

Returns:

the currently existing next run time for that jobId; null if no such job exists or if it exists but its schedule prevents it from ever running again.

getVersion

@Nullable
Long getVersion(com.atlassian.scheduler.config.JobId jobId)

Returns the current version of the persisted clustered job with this ID.

Implementations MAY implement this with:

     ClusteredJob clusteredJob = find(jobId);
     return (clusteredJob != null) ? clusteredJob.getVersion() : null;
 

However, this would be wasteful, and implementations SHOULD use a more efficient query when possible.

Parameters:

jobId - the job ID whose existence and current version is to be checked

Returns:

the currently existing version for that jobId, or null if no such job exists

find

@Nullable
ClusteredJob find(com.atlassian.scheduler.config.JobId jobId)

Finds and returns the persisted details for a clustered job.

Parameters:

jobId - the job ID for the job details to be loaded

Returns:

the existing job details, or null if the job does not exist

findByJobRunnerKey

@Nonnull
Collection<ClusteredJob> findByJobRunnerKey(com.atlassian.scheduler.config.JobRunnerKey jobRunnerKey)

Returns all jobs that use the given job runner.

Implementations:

• SHOULD issue a query of the form SELECT * FROM jobs WHERE jobRunnerKey = ? to retrieve all job details that match the given jobRunnerKey.
• MUST return a ClusteredJob for each clustered job that has been persisted with the specified jobRunnerKey.

Parameters:

jobRunnerKey - the job runner key for which to search

Returns:

the set of clustered jobs with the given job runner, in no particular order

refresh

@Nonnull
Map<com.atlassian.scheduler.config.JobId,Date> refresh()

Returns the job ID and next run time for every clustered job that should be in the queue.

Implementations:

• SHOULD issue a query of the form SELECT jobId, nextRunTime FROM jobs WHERE nextRunTime IS NOT NULL to retrieve all existing job IDs that have scheduled next time to run.
• MUST return a mapping of all job IDs to the next run time for that job ID. The keys and values MUST NOT be null for any entry in the returned map.

findAllJobRunnerKeys

@Nonnull
Set<com.atlassian.scheduler.config.JobRunnerKey> findAllJobRunnerKeys()

Returns the set of distinct job runner keys that have at least one job schedule stored here.

Implementations:

• SHOULD issue a query of the form SELECT DISTINCT jobRunnerKey FROM jobs to retrieve all unique job runner keys.
• MUST return the canonical set of job runner keys, regardless of whether or not they have any jobs that will ever run again — that is, it does not matter whether the nextRunTime is null or not.

Returns:

the canonical set of all job runner keys that have at least one scheduled job, whether it will ever run again or not

create

boolean create(ClusteredJob clusteredJob)

Called to create a new clustered job in the database.

Implementations:

• SHOULD issue a statement of the form INSERT INTO jobs ... VALUES ... to create a representation of this job.
• MUST return false rather than throw an exception if the request fails due to a UNIQUE constraint
• MAY attempt to determine such failures with a SELECT for a conflicting entry if the persistence layer does not make it possible to distinguish UNIQUE constraint failures reliably.

Parameters:

clusteredJob - the job details to be created

updateNextRunTime

boolean updateNextRunTime(com.atlassian.scheduler.config.JobId jobId,
                          @Nullable
                          Date nextRunTime,
                          long expectedVersion)

Updates the next run time for an existing clustered job.

Implementations:

• SHOULD issue a statement of the form UPDATE jobs SET nextRunTime = ?, version = ? WHERE jobId = ? AND version = ?
• MUST ensure that the update occurs if and only if the job is already persisted with the expected version.
• MUST change the version as part of the update
• MUST return false if no rows are updated, whether because the job does not exist or because the specified version is incorrect.

Parameters:

jobId - the job ID for which to update the next run time

nextRunTime - the new next run time, or null if it will never run again

expectedVersion - the version of the job details that are expected to be found

Returns:

true if the update is successful; false otherwise

delete

boolean delete(com.atlassian.scheduler.config.JobId jobId)

Called to remove a scheduled cluster job by its ID.

Implementations:

• SHOULD issue a statement of the form DELETE FROM jobs WHERE jobId = ?
• MUST return false if there is no matching row to delete; note that this is not an error and the implementation MUST NOT throw an exception for it

Parameters:

jobId - the job to be unscheduled

Returns:

true if the job is successfully removed; false, otherwise