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}