001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.scheduling;
018
019import java.time.Duration;
020import java.time.Instant;
021import java.util.Date;
022import java.util.concurrent.ScheduledFuture;
023
024import org.springframework.lang.Nullable;
025
026/**
027 * Task scheduler interface that abstracts the scheduling of
028 * {@link Runnable Runnables} based on different kinds of triggers.
029 *
030 * <p>This interface is separate from {@link SchedulingTaskExecutor} since it
031 * usually represents for a different kind of backend, i.e. a thread pool with
032 * different characteristics and capabilities. Implementations may implement
033 * both interfaces if they can handle both kinds of execution characteristics.
034 *
035 * <p>The 'default' implementation is
036 * {@link org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler},
037 * wrapping a native {@link java.util.concurrent.ScheduledExecutorService}
038 * and adding extended trigger capabilities.
039 *
040 * <p>This interface is roughly equivalent to a JSR-236
041 * {@code ManagedScheduledExecutorService} as supported in Java EE 7
042 * environments but aligned with Spring's {@code TaskExecutor} model.
043 *
044 * @author Juergen Hoeller
045 * @since 3.0
046 * @see org.springframework.core.task.TaskExecutor
047 * @see java.util.concurrent.ScheduledExecutorService
048 * @see org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler
049 */
050public interface TaskScheduler {
051
052        /**
053         * Schedule the given {@link Runnable}, invoking it whenever the trigger
054         * indicates a next execution time.
055         * <p>Execution will end once the scheduler shuts down or the returned
056         * {@link ScheduledFuture} gets cancelled.
057         * @param task the Runnable to execute whenever the trigger fires
058         * @param trigger an implementation of the {@link Trigger} interface,
059         * e.g. a {@link org.springframework.scheduling.support.CronTrigger} object
060         * wrapping a cron expression
061         * @return a {@link ScheduledFuture} representing pending completion of the task,
062         * or {@code null} if the given Trigger object never fires (i.e. returns
063         * {@code null} from {@link Trigger#nextExecutionTime})
064         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
065         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
066         * @see org.springframework.scheduling.support.CronTrigger
067         */
068        @Nullable
069        ScheduledFuture<?> schedule(Runnable task, Trigger trigger);
070
071        /**
072         * Schedule the given {@link Runnable}, invoking it at the specified execution time.
073         * <p>Execution will end once the scheduler shuts down or the returned
074         * {@link ScheduledFuture} gets cancelled.
075         * @param task the Runnable to execute whenever the trigger fires
076         * @param startTime the desired execution time for the task
077         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
078         * @return a {@link ScheduledFuture} representing pending completion of the task
079         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
080         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
081         * @since 5.0
082         * @see #schedule(Runnable, Date)
083         */
084        default ScheduledFuture<?> schedule(Runnable task, Instant startTime) {
085                return schedule(task, Date.from(startTime));
086        }
087
088        /**
089         * Schedule the given {@link Runnable}, invoking it at the specified execution time.
090         * <p>Execution will end once the scheduler shuts down or the returned
091         * {@link ScheduledFuture} gets cancelled.
092         * @param task the Runnable to execute whenever the trigger fires
093         * @param startTime the desired execution time for the task
094         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
095         * @return a {@link ScheduledFuture} representing pending completion of the task
096         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
097         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
098         */
099        ScheduledFuture<?> schedule(Runnable task, Date startTime);
100
101        /**
102         * Schedule the given {@link Runnable}, invoking it at the specified execution time
103         * and subsequently with the given period.
104         * <p>Execution will end once the scheduler shuts down or the returned
105         * {@link ScheduledFuture} gets cancelled.
106         * @param task the Runnable to execute whenever the trigger fires
107         * @param startTime the desired first execution time for the task
108         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
109         * @param period the interval between successive executions of the task
110         * @return a {@link ScheduledFuture} representing pending completion of the task
111         * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
112         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
113         * @since 5.0
114         * @see #scheduleAtFixedRate(Runnable, Date, long)
115         */
116        default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Instant startTime, Duration period) {
117                return scheduleAtFixedRate(task, Date.from(startTime), period.toMillis());
118        }
119
120        /**
121         * Schedule the given {@link Runnable}, invoking it at the specified execution time
122         * and subsequently with the given period.
123         * <p>Execution will end once the scheduler shuts down or the returned
124         * {@link ScheduledFuture} gets cancelled.
125         * @param task the Runnable to execute whenever the trigger fires
126         * @param startTime the desired first execution time for the task
127         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
128         * @param period the interval between successive executions of the task (in milliseconds)
129         * @return a {@link ScheduledFuture} representing pending completion of the task
130         * @throws org.springframework.core.task.TaskRejectedException if  the given task was not accepted
131         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
132         */
133        ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Date startTime, long period);
134
135        /**
136         * Schedule the given {@link Runnable}, starting as soon as possible and
137         * invoking it with the given period.
138         * <p>Execution will end once the scheduler shuts down or the returned
139         * {@link ScheduledFuture} gets cancelled.
140         * @param task the Runnable to execute whenever the trigger fires
141         * @param period the interval between successive executions of the task
142         * @return a {@link ScheduledFuture} representing pending completion of the task
143         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
144         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
145         * @since 5.0
146         * @see #scheduleAtFixedRate(Runnable, long)
147         */
148        default ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Duration period) {
149                return scheduleAtFixedRate(task, period.toMillis());
150        }
151
152        /**
153         * Schedule the given {@link Runnable}, starting as soon as possible and
154         * invoking it with the given period.
155         * <p>Execution will end once the scheduler shuts down or the returned
156         * {@link ScheduledFuture} gets cancelled.
157         * @param task the Runnable to execute whenever the trigger fires
158         * @param period the interval between successive executions of the task (in milliseconds)
159         * @return a {@link ScheduledFuture} representing pending completion of the task
160         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
161         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
162         */
163        ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period);
164
165        /**
166         * Schedule the given {@link Runnable}, invoking it at the specified execution time
167         * and subsequently with the given delay between the completion of one execution
168         * and the start of the next.
169         * <p>Execution will end once the scheduler shuts down or the returned
170         * {@link ScheduledFuture} gets cancelled.
171         * @param task the Runnable to execute whenever the trigger fires
172         * @param startTime the desired first execution time for the task
173         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
174         * @param delay the delay between the completion of one execution and the start of the next
175         * @return a {@link ScheduledFuture} representing pending completion of the task
176         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
177         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
178         * @since 5.0
179         * @see #scheduleWithFixedDelay(Runnable, Date, long)
180         */
181        default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Instant startTime, Duration delay) {
182                return scheduleWithFixedDelay(task, Date.from(startTime), delay.toMillis());
183        }
184
185        /**
186         * Schedule the given {@link Runnable}, invoking it at the specified execution time
187         * and subsequently with the given delay between the completion of one execution
188         * and the start of the next.
189         * <p>Execution will end once the scheduler shuts down or the returned
190         * {@link ScheduledFuture} gets cancelled.
191         * @param task the Runnable to execute whenever the trigger fires
192         * @param startTime the desired first execution time for the task
193         * (if this is in the past, the task will be executed immediately, i.e. as soon as possible)
194         * @param delay the delay between the completion of one execution and the start of the next
195         * (in milliseconds)
196         * @return a {@link ScheduledFuture} representing pending completion of the task
197         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
198         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
199         */
200        ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Date startTime, long delay);
201
202        /**
203         * Schedule the given {@link Runnable}, starting as soon as possible and invoking it with
204         * the given delay between the completion of one execution and the start of the next.
205         * <p>Execution will end once the scheduler shuts down or the returned
206         * {@link ScheduledFuture} gets cancelled.
207         * @param task the Runnable to execute whenever the trigger fires
208         * @param delay the delay between the completion of one execution and the start of the next
209         * @return a {@link ScheduledFuture} representing pending completion of the task
210         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
211         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
212         * @since 5.0
213         * @see #scheduleWithFixedDelay(Runnable, long)
214         */
215        default ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Duration delay) {
216                return scheduleWithFixedDelay(task, delay.toMillis());
217        }
218
219        /**
220         * Schedule the given {@link Runnable}, starting as soon as possible and invoking it with
221         * the given delay between the completion of one execution and the start of the next.
222         * <p>Execution will end once the scheduler shuts down or the returned
223         * {@link ScheduledFuture} gets cancelled.
224         * @param task the Runnable to execute whenever the trigger fires
225         * @param delay the delay between the completion of one execution and the start of the next
226         * (in milliseconds)
227         * @return a {@link ScheduledFuture} representing pending completion of the task
228         * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted
229         * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)
230         */
231        ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long delay);
232
233}