org.apache.sling.commons.scheduler

Interface Scheduler

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. If both properties are specified, only PROPERTY_SCHEDULER_PERIOD is considered for scheduling. 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 java.lang.String	PROPERTY_SCHEDULER_CONCURRENT Name of the configuration property to define if the job can be run concurrently.
static java.lang.String	PROPERTY_SCHEDULER_EXPRESSION Name of the configuration property to define the cron expression for a job.
static java.lang.String	PROPERTY_SCHEDULER_IMMEDIATE Name of the configuration property to define if a periodically job should be scheduled immediate.
static java.lang.String	PROPERTY_SCHEDULER_NAME Name of the configuration property to define the job name.
static java.lang.String	PROPERTY_SCHEDULER_PERIOD Name of the configuration property to define the period for a job.
static java.lang.String	PROPERTY_SCHEDULER_RUN_ON Name of the configuration property to define the instances this job should run on.
static java.lang.String	PROPERTY_SCHEDULER_THREAD_POOL Name of the configuration property to define the thread pool to be used.
static java.lang.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 java.lang.String	VALUE_RUN_ON_LEADER Value for PROPERTY_SCHEDULER_RUN_ON to run the job on the leader only.
static java.lang.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(java.lang.String name, java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, java.lang.String schedulingExpression, boolean canRunConcurrently) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	addPeriodicJob(java.lang.String name, java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, long period, boolean canRunConcurrently) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	addPeriodicJob(java.lang.String name, java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, long period, boolean canRunConcurrently, boolean startImmediate) Deprecated. Use schedule(Object, ScheduleOptions) instead.
ScheduleOptions	AT(java.util.Date date) Create a schedule options to fire a job once at a specific date.
ScheduleOptions	AT(java.util.Date date, int times, long period) Create a schedule options to fire a job period starting at a specific date.
ScheduleOptions	EXPR(java.lang.String expression) Create a schedule options to schedule the job based on the expression.
void	fireJob(java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config) Deprecated. Use schedule(Object, ScheduleOptions) instead.
boolean	fireJob(java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, int times, long period) Deprecated. Use schedule(Object, ScheduleOptions) instead.
void	fireJobAt(java.lang.String name, java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, java.util.Date date) Deprecated. Use schedule(Object, ScheduleOptions) instead.
boolean	fireJobAt(java.lang.String name, java.lang.Object job, java.util.Map<java.lang.String,java.io.Serializable> config, java.util.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(java.lang.String name) Deprecated. Use unschedule(String) instead.
boolean	schedule(java.lang.Object job, ScheduleOptions options) Schedule a job based on the options.
boolean	unschedule(java.lang.String jobName) Remove a scheduled job by name.

Field Detail

PROPERTY_SCHEDULER_PERIOD

static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String PROPERTY_SCHEDULER_NAME

Name of the configuration property to define the job name.

See Also:

Constant Field Values

PROPERTY_SCHEDULER_TIMES

static final java.lang.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 java.lang.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 where the scheduler has been instructed to schedule the job, e.g. if the same code is running on all instances. This property can be configured with: - 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. 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 java.lang.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 java.lang.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

PROPERTY_SCHEDULER_THREAD_POOL

static final java.lang.String PROPERTY_SCHEDULER_THREAD_POOL

Name of the configuration property to define the thread pool to be used. Scheduled jobs can run using different thread pools. By default, the default thread pool of the scheduler is used. If a thread pool name is specified, it is up to the scheduler to put the job in the defined thread pool or any other thread pool. This option must be used with special care as it might create new thread pools. It should only be used if there is a good reason to not use the default thread pool.

Since:

2.5.0

See Also:

Constant Field Values

Method Detail

schedule

boolean schedule(java.lang.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. The job is only started on this instance - if it is started at all. The options for running on a single instance, on the leader etc. (see ScheduleOptions.onInstancesOnly(String[]), ScheduleOptions.onLeaderOnly(boolean), and ScheduleOptions.onSingleInstanceOnly(boolean)) are only useful, if the same job is scheduled on all instances in a cluster. In this case this extra configuration controls on which instances the job is really started. Using the above options might not start the job on the current instance, for example if the current instance is not the leader.

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(java.lang.String jobName)

Remove a scheduled job by name.

Parameters:

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

Returns:

The schedule options.

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

Returns:

The schedule options.

Since:

2.3

AT

ScheduleOptions AT(java.util.Date date)

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

In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job.

Parameters:

date - The date this job should be run.

Returns:

The schedule options.

Since:

2.3

AT

ScheduleOptions AT(java.util.Date date,
                   int times,
                   long period)

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

In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time the behavior depends on the times parameter:

1. If times is -1 (meaning unlimited repetitions) there will be no immediate action. Instead the scheduler just waits for next scheduled interval.
2. Otherwise (limited amount of repitions) the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job. Then the scheduler waits desired interval and executes all remaining triggers. Effectively the first fire time of the misfired trigger is moved to current time with no other changes.

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

Returns:

The schedule options.

Since:

2.3

EXPR

ScheduleOptions EXPR(java.lang.String expression)

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

In case the scheduled time was missed due to the Scheduler not running or no thread being available at that point in time the job will be executed only once, as soon as the Scheduler is running again and a thread is available for processing the job. No matter how many trigger executions were missed, only a single immediate execution is performed.

Parameters:

expression - The cron exception

Returns:

The schedule options.

Since:

2.3

addJob

@Deprecated
void addJob(java.lang.String name,
                        java.lang.Object job,
                        java.util.Map<java.lang.String,java.io.Serializable> config,
                        java.lang.String schedulingExpression,
                        boolean canRunConcurrently)
                 throws java.lang.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:

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

java.lang.Exception - If the job can't be scheduled.

addPeriodicJob

@Deprecated
void addPeriodicJob(java.lang.String name,
                                java.lang.Object job,
                                java.util.Map<java.lang.String,java.io.Serializable> config,
                                long period,
                                boolean canRunConcurrently)
                         throws java.lang.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

java.lang.Exception - If the job can't be scheduled.

addPeriodicJob

@Deprecated
void addPeriodicJob(java.lang.String name,
                                java.lang.Object job,
                                java.util.Map<java.lang.String,java.io.Serializable> config,
                                long period,
                                boolean canRunConcurrently,
                                boolean startImmediate)
                         throws java.lang.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

java.lang.Exception - If the job can't be scheduled.

Since:

2.2

fireJob

@Deprecated
void fireJob(java.lang.Object job,
                         java.util.Map<java.lang.String,java.io.Serializable> config)
                  throws java.lang.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

java.lang.Exception - If the job can't be scheduled.

fireJob

@Deprecated
boolean fireJob(java.lang.Object job,
                            java.util.Map<java.lang.String,java.io.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

Since:

2.1

fireJobAt

@Deprecated
void fireJobAt(java.lang.String name,
                           java.lang.Object job,
                           java.util.Map<java.lang.String,java.io.Serializable> config,
                           java.util.Date date)
                    throws java.lang.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

java.lang.Exception - If the job can't be scheduled.

fireJobAt

@Deprecated
boolean fireJobAt(java.lang.String name,
                              java.lang.Object job,
                              java.util.Map<java.lang.String,java.io.Serializable> config,
                              java.util.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:

java.lang.IllegalArgumentException - If the job has not the correct type.

Since:

2.1

removeJob

@Deprecated
void removeJob(java.lang.String name)
                    throws java.util.NoSuchElementException

Deprecated. Use unschedule(String) instead.

Remove a scheduled job by name.

Parameters:

name - The name of the job.

Throws:

java.util.NoSuchElementException - If the job is not scheduled.