TaskScheduler (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.scheduling

## Interface TaskScheduler

- All Known Implementing Classes:
    ConcurrentTaskScheduler, ThreadPoolTaskScheduler, TimerManagerTaskScheduler

      public interface TaskScheduler

  Task scheduler interface that abstracts the scheduling of `Runnables` based on different kinds of triggers.

  This interface is separate from `SchedulingTaskExecutor` since it usually represents for a different kind of backend, i.e. a thread pool with different characteristics and capabilities. Implementations may implement both interfaces if they can handle both kinds of execution characteristics.

  The 'default' implementation is `ThreadPoolTaskScheduler`, wrapping a native `ScheduledExecutorService` and adding extended trigger capabilities.

  This interface is roughly equivalent to a JSR-236 `ManagedScheduledExecutorService` as supported in Java EE 6 environments. However, at the time of the Spring 3.0 release, the JSR-236 interfaces have not been released in official form yet.

  Since:
    3.0
  Author:
    Juergen Hoeller
  See Also:
    `TaskExecutor`, `ScheduledExecutorService`, `ThreadPoolTaskScheduler`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ScheduledFuture` | `schedule(Runnable task, Date startTime)` Schedule the given `Runnable`, invoking it at the specified execution time.
    `ScheduledFuture` | `schedule(Runnable task, Trigger trigger)` Schedule the given `Runnable`, invoking it whenever the trigger indicates a next execution time.
    `ScheduledFuture` | `scheduleAtFixedRate(Runnable task, Date startTime, long period)` Schedule the given `Runnable`, invoking it at the specified execution time and subsequently with the given period.
    `ScheduledFuture` | `scheduleAtFixedRate(Runnable task, long period)` Schedule the given `Runnable`, starting as soon as possible and invoking it with the given period.
    `ScheduledFuture` | `scheduleWithFixedDelay(Runnable task, Date startTime, long delay)` Schedule the given `Runnable`, invoking it at the specified execution time and subsequently with the given delay between the completion of one execution and the start of the next.
    `ScheduledFuture` | `scheduleWithFixedDelay(Runnable task, long delay)` Schedule the given `Runnable`, starting as soon as possible and invoking it with the given delay between the completion of one execution and the start of the next.

- - ### Method Detail

    - #### schedule

          ScheduledFuture schedule(Runnable task,
                                 Trigger trigger)

      Schedule the given `Runnable`, invoking it whenever the trigger indicates a next execution time.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `trigger` - an implementation of the `Trigger` interface, e.g. a `CronTrigger` object wrapping a cron expression
      Returns:
        a `ScheduledFuture` representing pending completion of the task, or `null` if the given Trigger object never fires (i.e. returns `null` from `Trigger.nextExecutionTime(org.springframework.scheduling.TriggerContext)`)
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
      See Also:
        `CronTrigger`

    - #### schedule

          ScheduledFuture schedule(Runnable task,
                                 Date startTime)

      Schedule the given `Runnable`, invoking it at the specified execution time.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `startTime` - the desired execution time for the task (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
      Returns:
        a `ScheduledFuture` representing pending completion of the task
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)

    - #### scheduleAtFixedRate

          ScheduledFuture scheduleAtFixedRate(Runnable task,
                                            Date startTime,
                                            long period)

      Schedule the given `Runnable`, invoking it at the specified execution time and subsequently with the given period.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `startTime` - the desired first execution time for the task (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
        `period` - the interval between successive executions of the task (in milliseconds)
      Returns:
        a `ScheduledFuture` representing pending completion of the task
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)

    - #### scheduleAtFixedRate

          ScheduledFuture scheduleAtFixedRate(Runnable task,
                                            long period)

      Schedule the given `Runnable`, starting as soon as possible and invoking it with the given period.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `period` - the interval between successive executions of the task (in milliseconds)
      Returns:
        a `ScheduledFuture` representing pending completion of the task
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)

    - #### scheduleWithFixedDelay

          ScheduledFuture scheduleWithFixedDelay(Runnable task,
                                               Date startTime,
                                               long delay)

      Schedule the given `Runnable`, invoking it at the specified execution time and subsequently with the given delay between the completion of one execution and the start of the next.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `startTime` - the desired first execution time for the task (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
        `delay` - the delay between the completion of one execution and the start of the next (in milliseconds)
      Returns:
        a `ScheduledFuture` representing pending completion of the task
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)

    - #### scheduleWithFixedDelay

          ScheduledFuture scheduleWithFixedDelay(Runnable task,
                                               long delay)

      Schedule the given `Runnable`, starting as soon as possible and invoking it with the given delay between the completion of one execution and the start of the next.

      Execution will end once the scheduler shuts down or the returned `ScheduledFuture` gets cancelled.

      Parameters:
        `task` - the Runnable to execute whenever the trigger fires
        `delay` - the interval between successive executions of the task (in milliseconds)
      Returns:
        a `ScheduledFuture` representing pending completion of the task
      Throws:
        `TaskRejectedException` - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)