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

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