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

org.springframework.scheduling.concurrent

## Class ThreadPoolTaskScheduler

- java.lang.Object
- - org.springframework.util.CustomizableThreadCreator
  - - org.springframework.scheduling.concurrent.CustomizableThreadFactory
    - - org.springframework.scheduling.concurrent.ExecutorConfigurationSupport
      - - org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler

- All Implemented Interfaces:
    Serializable, Executor, ThreadFactory, Aware, BeanNameAware, DisposableBean, InitializingBean, AsyncTaskExecutor, TaskExecutor, SchedulingTaskExecutor, TaskScheduler

      public class ThreadPoolTaskScheduler
      extends ExecutorConfigurationSupport
      implements TaskScheduler, SchedulingTaskExecutor

  Implementation of Spring's `TaskScheduler` interface, wrapping a native `ScheduledThreadPoolExecutor`.
  Since:
    3.0
  Author:
    Juergen Hoeller, Mark Fisher
  See Also:
    `setPoolSize(int)`, `ExecutorConfigurationSupport.setThreadFactory(java.util.concurrent.ThreadFactory)`, `setErrorHandler(org.springframework.util.ErrorHandler)`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from class org.springframework.scheduling.concurrent.ExecutorConfigurationSupport

      `logger`

    - ### Fields inherited from interface org.springframework.core.task.AsyncTaskExecutor

      `TIMEOUT_IMMEDIATE, TIMEOUT_INDEFINITE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ThreadPoolTaskScheduler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected ScheduledExecutorService` | `createExecutor(int poolSize, ThreadFactory threadFactory, RejectedExecutionHandler rejectedExecutionHandler)` Create a new `ScheduledExecutorService` instance.
    `void` | `execute(Runnable task)` Execute the given `task`.
    `void` | `execute(Runnable task, long startTimeout)` Execute the given `task`.
    `ScheduledExecutorService` | `getScheduledExecutor()` Return the underlying ScheduledExecutorService for native access.
    `protected ExecutorService` | `initializeExecutor(ThreadFactory threadFactory, RejectedExecutionHandler rejectedExecutionHandler)` Create the target `ExecutorService` instance.
    `boolean` | `prefersShortLivedTasks()` Does this `TaskExecutor` prefer short-lived tasks over long-lived tasks?
    `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.
    `void` | `setErrorHandler(ErrorHandler errorHandler)` Provide an `ErrorHandler` strategy.
    `void` | `setPoolSize(int poolSize)` Set the ScheduledExecutorService's pool size.
    `<T> Future<T>` | `submit(Callable<T> task)` Submit a Callable task for execution, receiving a Future representing that task.
    `Future<?>` | `submit(Runnable task)` Submit a Runnable task for execution, receiving a Future representing that task.

    - ### Methods inherited from class org.springframework.scheduling.concurrent.ExecutorConfigurationSupport

      `afterPropertiesSet, destroy, initialize, setAwaitTerminationSeconds, setBeanName, setRejectedExecutionHandler, setThreadFactory, setThreadNamePrefix, setWaitForTasksToCompleteOnShutdown, shutdown`

    - ### Methods inherited from class org.springframework.scheduling.concurrent.CustomizableThreadFactory

      `newThread`

    - ### Methods inherited from class org.springframework.util.CustomizableThreadCreator

      `createThread, getDefaultThreadNamePrefix, getThreadGroup, getThreadNamePrefix, getThreadPriority, isDaemon, nextThreadName, setDaemon, setThreadGroup, setThreadGroupName, setThreadPriority`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ThreadPoolTaskScheduler

          public ThreadPoolTaskScheduler()

  - ### Method Detail

    - #### setPoolSize

          public void setPoolSize(int poolSize)

      Set the ScheduledExecutorService's pool size. Default is 1.

    - #### setErrorHandler

          public void setErrorHandler(ErrorHandler errorHandler)

      Provide an `ErrorHandler` strategy.

    - #### initializeExecutor

          protected ExecutorService initializeExecutor(ThreadFactory threadFactory,
                                           RejectedExecutionHandler rejectedExecutionHandler)

      Description copied from class: `ExecutorConfigurationSupport`
      Create the target `ExecutorService` instance. Called by `afterPropertiesSet`.
      Specified by:
        `initializeExecutor` in class `ExecutorConfigurationSupport`
      Parameters:
        `threadFactory` - the ThreadFactory to use
        `rejectedExecutionHandler` - the RejectedExecutionHandler to use
      Returns:
        a new ExecutorService instance
      See Also:
        `ExecutorConfigurationSupport.afterPropertiesSet()`

    - #### createExecutor

          protected ScheduledExecutorService createExecutor(int poolSize,
                                                ThreadFactory threadFactory,
                                                RejectedExecutionHandler rejectedExecutionHandler)

      Create a new `ScheduledExecutorService` instance.

      The default implementation creates a `ScheduledThreadPoolExecutor`. Can be overridden in subclasses to provide custom `ScheduledExecutorService` instances.

      Parameters:
        `poolSize` - the specified pool size
        `threadFactory` - the ThreadFactory to use
        `rejectedExecutionHandler` - the RejectedExecutionHandler to use
      Returns:
        a new ScheduledExecutorService instance
      See Also:
        `ExecutorConfigurationSupport.afterPropertiesSet()`, `ScheduledThreadPoolExecutor`

    - #### getScheduledExecutor

          public ScheduledExecutorService getScheduledExecutor()
                                                        throws IllegalStateException

      Return the underlying ScheduledExecutorService for native access.
      Returns:
        the underlying ScheduledExecutorService (never `null`)
      Throws:
        `IllegalStateException` - if the ThreadPoolTaskScheduler hasn't been initialized yet

    - #### execute

          public void execute(Runnable task)

      Description copied from interface: `TaskExecutor`
      Execute the given `task`.

      The call might return immediately if the implementation uses an asynchronous execution strategy, or might block in the case of synchronous execution.

      Specified by:
        `execute` in interface `Executor`
      Specified by:
        `execute` in interface `TaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)

    - #### execute

          public void execute(Runnable task,
                     long startTimeout)

      Description copied from interface: `AsyncTaskExecutor`
      Execute the given `task`.
      Specified by:
        `execute` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)
        `startTimeout` - the time duration (milliseconds) within which the task is supposed to start. This is intended as a hint to the executor, allowing for preferred handling of immediate tasks. Typical values are `AsyncTaskExecutor.TIMEOUT_IMMEDIATE` or `AsyncTaskExecutor.TIMEOUT_INDEFINITE` (the default as used by `TaskExecutor.execute(Runnable)`).

    - #### submit

          public Future<?> submit(Runnable task)

      Description copied from interface: `AsyncTaskExecutor`
      Submit a Runnable task for execution, receiving a Future representing that task. The Future will return a `null` result upon completion.
      Specified by:
        `submit` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)
      Returns:
        a Future representing pending completion of the task

    - #### submit

          public <T> Future<T> submit(Callable<T> task)

      Description copied from interface: `AsyncTaskExecutor`
      Submit a Callable task for execution, receiving a Future representing that task. The Future will return the Callable's result upon completion.
      Specified by:
        `submit` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Callable` to execute (never `null`)
      Returns:
        a Future representing pending completion of the task

    - #### prefersShortLivedTasks

          public boolean prefersShortLivedTasks()

      Description copied from interface: `SchedulingTaskExecutor`
      Does this `TaskExecutor` prefer short-lived tasks over long-lived tasks?

      A `SchedulingTaskExecutor` implementation can indicate whether it prefers submitted tasks to perform as little work as they can within a single task execution. For example, submitted tasks might break a repeated loop into individual subtasks which submit a follow-up task afterwards (if feasible).

      This should be considered a hint. Of course `TaskExecutor` clients are free to ignore this flag and hence the `SchedulingTaskExecutor` interface overall. However, thread pools will usually indicated a preference for short-lived tasks, to be able to perform more fine-grained scheduling.

      Specified by:
        `prefersShortLivedTasks` in interface `SchedulingTaskExecutor`
      Returns:
        `true` if this `TaskExecutor` prefers short-lived tasks

    - #### schedule

          public ScheduledFuture schedule(Runnable task,
                                 Trigger trigger)

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `schedule` in interface `TaskScheduler`
      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)`)
      See Also:
        `CronTrigger`

    - #### schedule

          public ScheduledFuture schedule(Runnable task,
                                 Date startTime)

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `schedule` in interface `TaskScheduler`
      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

    - #### scheduleAtFixedRate

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

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `scheduleAtFixedRate` in interface `TaskScheduler`
      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

    - #### scheduleAtFixedRate

          public ScheduledFuture scheduleAtFixedRate(Runnable task,
                                            long period)

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `scheduleAtFixedRate` in interface `TaskScheduler`
      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

    - #### scheduleWithFixedDelay

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

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `scheduleWithFixedDelay` in interface `TaskScheduler`
      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

    - #### scheduleWithFixedDelay

          public ScheduledFuture scheduleWithFixedDelay(Runnable task,
                                               long delay)

      Description copied from interface: `TaskScheduler`
      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.

      Specified by:
        `scheduleWithFixedDelay` in interface `TaskScheduler`
      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