org.apache.sling.commons.scheduler

Interface Scheduler

@ProviderType
public interface Scheduler

A scheduler to schedule time/cron based jobs. A job is an object that is executed/fired by the scheduler. The object should either implement the Job interface or the Runnable interface. A job can be scheduled either by creating a ScheduleOptions instance through one of the scheduler methods and then calling schedule(Object, ScheduleOptions) or by using the whiteboard pattern and registering a Runnable service with either the PROPERTY_SCHEDULER_EXPRESSION or PROPERTY_SCHEDULER_PERIOD property. Services registered by the whiteboard pattern can by default run concurrently, which usually is not wanted. Therefore it is advisable to also set the PROPERTY_SCHEDULER_CONCURRENT property with Boolean.FALSE. Jobs started through the scheduler API are not persisted and are not restarted after a bundle restart. If the client bundle is stopped, the scheduler will stop all jobs started by this bundle as well. However, the client bundle does not need to keep a reference to the scheduler service.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROPERTY_SCHEDULER_CONCURRENT Name of the configuration property to define if the job can be run concurrently.
static String	PROPERTY_SCHEDULER_EXPRESSION Name of the configuration property to define the cron expression for a job.
static String	PROPERTY_SCHEDULER_IMMEDIATE Name of the configuration property to define if a periodically job should be scheduled immediate.
static String	PROPERTY_SCHEDULER_NAME Name of the configuration property to define the job name.
static String	PROPERTY_SCHEDULER_PERIOD Name of the configuration property to define the period for a job.
static String	PROPERTY_SCHEDULER_RUN_ON Name of the configuration property to define the instances this job should run on.
static String	PROPERTY_SCHEDULER_TIMES Name of the optional configuration property to define the number of times the job should be executed when PROPERTY_SCHEDULER_PERIOD is defined.
static String	VALUE_RUN_ON_LEADER Value for PROPERTY_SCHEDULER_RUN_ON to run the job on the leader only.
static String	VALUE_RUN_ON_SINGLE Value for PROPERTY_SCHEDULER_RUN_ON to run the job on a single instance only.

Method Summary

Modifier and Type	Method and Description
void	addJob(String name, Object job, Map<String,Serializable> config, String schedulingExpression, boolean canRunConcurrently) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	addPeriodicJob(String name, Object job, Map<String,Serializable> config, long period, boolean canRunConcurrently) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	addPeriodicJob(String name, Object job, Map<String,Serializable> config, long period, boolean canRunConcurrently, boolean startImmediate) Deprecated. Use schedule(Object, ScheduleOptions) instead.
ScheduleOptions	AT(Date date) Create a schedule options to fire a job once at a specific date
ScheduleOptions	AT(Date date, int times, long period) Create a schedule options to fire a job period starting at a specific date
ScheduleOptions	EXPR(String expression) Create a schedule options to schedule the job based on the expression
void	fireJob(Object job, Map<String,Serializable> config) Deprecated. Use schedule(Object, ScheduleOptions) instead.
boolean	fireJob(Object job, Map<String,Serializable> config, int times, long period) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	fireJobAt(String name, Object job, Map<String,Serializable> config, Date date) Deprecated. Use schedule(Object, ScheduleOptions) instead.
boolean	fireJobAt(String name, Object job, Map<String,Serializable> config, Date date, int times, long period) Deprecated. Use schedule(Object, ScheduleOptions) instead.
ScheduleOptions	NOW() Create a schedule options to fire a job immediately and only once.
ScheduleOptions	NOW(int times, long period) Create a schedule options to fire a job immediately more than once.
void	removeJob(String name) Deprecated. Use unschedule(String) instead.
boolean	schedule(Object job, ScheduleOptions options) Schedule a job based on the options.
boolean	unschedule(String jobName) Remove a scheduled job by name.

Field Detail

PROPERTY_SCHEDULER_PERIOD

static final String PROPERTY_SCHEDULER_PERIOD

Name of the configuration property to define the period for a job. The period is expressed in seconds. This property needs to be of type Long.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_IMMEDIATE

static final String PROPERTY_SCHEDULER_IMMEDIATE

Name of the configuration property to define if a periodically job should be scheduled immediate. Default is to not startup immediate, the job is started the first time after the period has expired. This property needs to be of type Boolean.

Since:

2.2.0 .

See Also:

Constant Field Values

PROPERTY_SCHEDULER_EXPRESSION

static final String PROPERTY_SCHEDULER_EXPRESSION

Name of the configuration property to define the cron expression for a job.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_CONCURRENT

static final String PROPERTY_SCHEDULER_CONCURRENT

Name of the configuration property to define if the job can be run concurrently.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_NAME

static final String PROPERTY_SCHEDULER_NAME

Name of the configuration property to define the job name.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_TIMES

static final String PROPERTY_SCHEDULER_TIMES

Name of the optional configuration property to define the number of times the job should be executed when PROPERTY_SCHEDULER_PERIOD is defined. This property is of type integer and must have a positive value.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_RUN_ON

static final String PROPERTY_SCHEDULER_RUN_ON

Name of the configuration property to define the instances this job should run on. By default a job is run on all instances. This property can be configured with: - a list of Sling IDs : in that case the job is only run on instances in this set. - constant VALUE_RUN_ON_LEADER : the job is only run on the leader - constant VALUE_RUN_ON_SINGLE : the job is only run on a single instance in a cluster. This is basically the same as VALUE_RUN_ON_LEADER but it's not further specified which single instance is used. Default is to start the job on all instances. This property needs to be of type String or String[]. If no topology information is available (= no Apache Sling Discovery Implementation active) this option is ignored, and the job is run on all instances.

Since:

2.3.0

See Also:

Constant Field Values

VALUE_RUN_ON_LEADER

static final String VALUE_RUN_ON_LEADER

Value for PROPERTY_SCHEDULER_RUN_ON to run the job on the leader only.

Since:

2.3.0

See Also:

Constant Field Values

VALUE_RUN_ON_SINGLE

static final String VALUE_RUN_ON_SINGLE

Value for PROPERTY_SCHEDULER_RUN_ON to run the job on a single instance only.

Since:

2.3.0

See Also:

Constant Field Values

Method Detail

schedule

boolean schedule(Object job,
                 ScheduleOptions options)

Schedule a job based on the options. Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job. The job object needs either to be a Job or a Runnable. The options have to be created by one of the provided methods from this scheduler.

Parameters:

job - The job to execute (either Job or Runnable).

options - Required options defining how to schedule the job

Returns:

true if the job could be added, false otherwise.

Since:

2.3

See Also:

NOW(), NOW(int, long), AT(Date), AT(Date, int, long), EXPR(String)

unschedule

boolean unschedule(String jobName)

Remove a scheduled job by name.

Parameters:

name - The name of the job.

Returns:

true if the job existed and could be stopped, false otherwise.

Since:

2.3

NOW

ScheduleOptions NOW()

Create a schedule options to fire a job immediately and only once.

Since:

2.3

NOW

ScheduleOptions NOW(int times,
                    long period)

Create a schedule options to fire a job immediately more than once.

Parameters:

times - The number of times this job should be started (must be higher than 1 or -1 for endless)

period - Every period seconds this job is started (must be at higher than 0).

Since:

2.3

AT

ScheduleOptions AT(Date date)

Create a schedule options to fire a job once at a specific date

Parameters:

date - The date this job should be run.

Since:

2.3

AT

ScheduleOptions AT(Date date,
                   int times,
                   long period)

Create a schedule options to fire a job period starting at a specific date

Parameters:

date - The date this job should be run.

times - The number of times this job should be started (must be higher than 1 or -1 for endless)

period - Every period seconds this job is started (must be at higher than 0).

Since:

2.3

EXPR

ScheduleOptions EXPR(String expression)

Create a schedule options to schedule the job based on the expression

Parameters:

expression - The cron exception

Since:

2.3

addJob

@Deprecated
void addJob(String name,
                        Object job,
                        Map<String,Serializable> config,
                        String schedulingExpression,
                        boolean canRunConcurrently)
                 throws Exception

Deprecated. Use schedule(Object, ScheduleOptions) instead.

/** Schedule a time based job. Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job.

Parameters:

name - The name of the job - or null. If no name is specified it can't be cancelled.

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

schedulingExpression - The time specification using a scheduling expression.

canRunConcurrently - Whether this job can run even if previous scheduled runs are still running.

Throws:

IllegalArgumentException - If the scheduling expression can't be parsed or if the job has not the correct type.

Exception - If the job can't be scheduled.

addPeriodicJob

@Deprecated
void addPeriodicJob(String name,
                                Object job,
                                Map<String,Serializable> config,
                                long period,
                                boolean canRunConcurrently)
                         throws Exception

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Schedule a periodic job. The job is started the first time when the period has passed. Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job.

Parameters:

name - The name of the job - or null. If no name is specified it can't be cancelled.

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

period - Every period seconds this job is started.

canRunConcurrently - Whether this job can run even if previous scheduled runs are still running.

Throws:

IllegalArgumentException - If the job has not the correct type.

Exception - If the job can't be scheduled.

addPeriodicJob

@Deprecated
void addPeriodicJob(String name,
                                Object job,
                                Map<String,Serializable> config,
                                long period,
                                boolean canRunConcurrently,
                                boolean startImmediate)
                         throws Exception

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Schedule a periodic job. Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job.

Parameters:

name - The name of the job - or null. If no name is specified it can't be cancelled.

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

period - Every period seconds this job is started.

canRunConcurrently - Whether this job can run even if previous scheduled runs are still running.

startImmediate - Whether to start the job immediately for the first time or wait for the period to expire.

Throws:

IllegalArgumentException - If the job has not the correct type.

Exception - If the job can't be scheduled.

Since:

2.2

fireJob

@Deprecated
void fireJob(Object job,
                         Map<String,Serializable> config)
                  throws Exception

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Fire a job immediately and only once.

Parameters:

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

Throws:

IllegalArgumentException - If the job has not the correct type.

Exception - If the job can't be scheduled.

fireJob

@Deprecated
boolean fireJob(Object job,
                            Map<String,Serializable> config,
                            int times,
                            long period)

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Fire a job immediately more than once.

Parameters:

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

times - The number of times this job should be started (must be higher than 1)

period - Every period seconds this job is started.

Returns:

true if the code could be added, false otherwise.

Throws:

IllegalArgumentException - If the job has not the correct type.

Since:

2.1

fireJobAt

@Deprecated
void fireJobAt(String name,
                           Object job,
                           Map<String,Serializable> config,
                           Date date)
                    throws Exception

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Fire a job once at a specific date Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job.

Parameters:

name - The name of the job - or null. If no name is specified it can't be cancelled.

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

date - The date this job should be run.

Throws:

IllegalArgumentException - If the job has not the correct type.

Exception - If the job can't be scheduled.

fireJobAt

@Deprecated
boolean fireJobAt(String name,
                              Object job,
                              Map<String,Serializable> config,
                              Date date,
                              int times,
                              long period)

Deprecated. Use schedule(Object, ScheduleOptions) instead.

Fire a job once at a specific date, several times with a given interval. Note that if a job with the same name has already been added, the old job is cancelled and this new job replaces the old job.

Parameters:

name - The name of the job - or null. If no name is specified it can't be cancelled.

job - The job to execute (either Job or Runnable).

config - An optional configuration object - this configuration is only passed to the job the job implements Job.

date - The date this job should be run.

times - The number of times this job should be started (must be higher than 1)

period - Every period seconds this job is started.

Returns:

true if the job could be added, false otherwise.

Throws:

IllegalArgumentException - If the job has not the correct type.

Since:

2.1

removeJob

@Deprecated
void removeJob(String name)
                    throws NoSuchElementException

Deprecated. Use unschedule(String) instead.

Remove a scheduled job by name.

Parameters:

name - The name of the job.

Throws:

NoSuchElementException - If the job is not scheduled.