org.springframework/spring-context/5.3.3 : org/springframework/scheduling/TaskScheduler.java

TaskScheduler
https://github.com/spring-projects/spring-framework: Spring Context (Spring IO)
Apache License, Version 2.0
Juergen Hoeller
/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.scheduling;

import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.Date;
import java.util.concurrent.ScheduledFuture;

import org.springframework.lang.Nullable;

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 7 environments but aligned with Spring's TaskExecutor model. 
Author: Juergen Hoeller
See Also: TaskExecutor
ScheduledExecutorService
ThreadPoolTaskScheduler
Since: 3.0/**
 * Task scheduler interface that abstracts the scheduling of
 * {@link Runnable Runnables} based on different kinds of triggers.
 *
 * <p>This interface is separate from {@link 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.
 *
 * <p>The 'default' implementation is
 * {@link org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler},
 * wrapping a native {@link java.util.concurrent.ScheduledExecutorService}
 * and adding extended trigger capabilities.
 *
 * <p>This interface is roughly equivalent to a JSR-236
 * {@code ManagedScheduledExecutorService} as supported in Java EE 7
 * environments but aligned with Spring's {@code TaskExecutor} model.
 *
 * @author Juergen Hoeller
 * @since 3.0
 * @see org.springframework.core.task.TaskExecutor
 * @see java.util.concurrent.ScheduledExecutorService
 * @see org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler
 */
public interface TaskScheduler {

	Return the clock to use for scheduling purposes.
See Also: Clock.systemDefaultZone()
Since: 5.3/**
	 * Return the clock to use for scheduling purposes.
	 * @since 5.3
	 * @see Clock#systemDefaultZone()
	 */
	default Clock getClock() {
		return Clock.systemDefaultZone();
	}

	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. 
Params: 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
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
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)/**
	 * Schedule the given {@link Runnable}, invoking it whenever the trigger
	 * indicates a next execution time.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param trigger an implementation of the {@link Trigger} interface,
	 * e.g. a {@link org.springframework.scheduling.support.CronTrigger} object
	 * wrapping a cron expression
	 * @return a {@link ScheduledFuture} representing pending completion of the task,
	 * or {@code null} if the given Trigger object never fires (i.e. returns
	 * {@code null} from {@link Trigger#nextExecutionTime})
	 * @throws org.springframework.core.task.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 org.springframework.scheduling.support.CronTrigger
	 */
	@Nullable
	ScheduledFuture<?> schedule(Runnable task, Trigger trigger);

	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. 
Params: 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)
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: schedule(Runnable, Date)
Returns: a ScheduledFuture representing pending completion of the task
Since: 5.0/**
	 * Schedule the given {@link Runnable}, invoking it at the specified execution time.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 * @since 5.0
	 * @see #schedule(Runnable, Date)
	 */
	default ScheduledFuture<?> schedule(Runnable task, Instant startTime) {
		return schedule(task, Date.from(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. 
Params: 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)
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)
Returns: a ScheduledFuture representing pending completion of the task/**
	 * Schedule the given {@link Runnable}, invoking it at the specified execution time.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 */
	ScheduledFuture<?> schedule(Runnable task, Date startTime);

	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. 
Params: 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
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: scheduleAtFixedRate(Runnable, Date, long)
Returns: a ScheduledFuture representing pending completion of the task
Since: 5.0/**
	 * Schedule the given {@link Runnable}, invoking it at the specified execution time
	 * and subsequently with the given period.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @param period the interval between successive executions of the task
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 * @since 5.0
	 * @see #scheduleAtFixedRate(Runnable, Date, long)
	 */
	default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Instant startTime, Duration period) {
		return scheduleAtFixedRate(task, Date.from(startTime), period.toMillis());
	}

	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. 
Params: 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)
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)
Returns: a ScheduledFuture representing pending completion of the task/**
	 * Schedule the given {@link Runnable}, invoking it at the specified execution time
	 * and subsequently with the given period.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @param period the interval between successive executions of the task (in milliseconds)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 */
	ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Date startTime, 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. 
Params: task – the Runnable to execute whenever the trigger fires
period – the interval between successive executions 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)
See Also: scheduleAtFixedRate(Runnable, long)
Returns: a ScheduledFuture representing pending completion of the task
Since: 5.0/**
	 * Schedule the given {@link Runnable}, starting as soon as possible and
	 * invoking it with the given period.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param period the interval between successive executions of the task
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 * @since 5.0
	 * @see #scheduleAtFixedRate(Runnable, long)
	 */
	default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Duration period) {
		return scheduleAtFixedRate(task, period.toMillis());
	}

	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. 
Params: task – the Runnable to execute whenever the trigger fires
period – the interval between successive executions of the task (in milliseconds)
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)
Returns: a ScheduledFuture representing pending completion of the task/**
	 * Schedule the given {@link Runnable}, starting as soon as possible and
	 * invoking it with the given period.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param period the interval between successive executions of the task (in milliseconds)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 */
	ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period);

	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. 
Params: 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
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: scheduleWithFixedDelay(Runnable, Date, long)
Returns: a ScheduledFuture representing pending completion of the task
Since: 5.0/**
	 * Schedule the given {@link 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.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @param delay the delay between the completion of one execution and the start of the next
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 * @since 5.0
	 * @see #scheduleWithFixedDelay(Runnable, Date, long)
	 */
	default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Instant startTime, Duration delay) {
		return scheduleWithFixedDelay(task, Date.from(startTime), delay.toMillis());
	}

	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. 
Params: 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)
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)
Returns: a ScheduledFuture representing pending completion of the task/**
	 * Schedule the given {@link 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.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param 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)
	 * @param delay the delay between the completion of one execution and the start of the next
	 * (in milliseconds)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 */
	ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Date startTime, 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. 
Params: task – the Runnable to execute whenever the trigger fires
delay – the delay between the completion of one execution and the start of the next
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: scheduleWithFixedDelay(Runnable, long)
Returns: a ScheduledFuture representing pending completion of the task
Since: 5.0/**
	 * Schedule the given {@link 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.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param delay the delay between the completion of one execution and the start of the next
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 * @since 5.0
	 * @see #scheduleWithFixedDelay(Runnable, long)
	 */
	default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Duration delay) {
		return scheduleWithFixedDelay(task, delay.toMillis());
	}

	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. 
Params: task – the Runnable to execute whenever the trigger fires
delay – the delay between the completion of one execution and the start of the next
(in milliseconds)
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)
Returns: a ScheduledFuture representing pending completion of the task/**
	 * Schedule the given {@link 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.
	 * <p>Execution will end once the scheduler shuts down or the returned
	 * {@link ScheduledFuture} gets cancelled.
	 * @param task the Runnable to execute whenever the trigger fires
	 * @param delay the delay between the completion of one execution and the start of the next
	 * (in milliseconds)
	 * @return a {@link ScheduledFuture} representing pending completion of the task
	 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
	 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
	 */
	ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long delay);

}
Author:	Juergen Hoeller
See Also:	TaskExecutor ScheduledExecutorService ThreadPoolTaskScheduler
Since:	3.0
Params:	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
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
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/ spring-context/ 5.3.3/ org/springframework/scheduling/TaskScheduler.java
