Package 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. If both properties are specified, only `PROPERTY_SCHEDULER_EXPRESSION` 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
`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_THREAD_POOL` Name of the configuration property to define the thread pool to be used.
`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

All Methods Instance Methods Abstract Methods Deprecated Methods
`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 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 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

#### PROPERTY_SCHEDULER_THREAD_POOL

    static final 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​(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​(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​(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​(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​(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​(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.