001/* 002 * Copyright 2002-2012 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.util.Date; 020import java.util.concurrent.ScheduledFuture; 021 022/** 023 * Task scheduler interface that abstracts the scheduling of 024 * {@link Runnable Runnables} based on different kinds of triggers. 025 * 026 * <p>This interface is separate from {@link SchedulingTaskExecutor} since it 027 * usually represents for a different kind of backend, i.e. a thread pool with 028 * different characteristics and capabilities. Implementations may implement 029 * both interfaces if they can handle both kinds of execution characteristics. 030 * 031 * <p>The 'default' implementation is 032 * {@link org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler}, 033 * wrapping a native {@link java.util.concurrent.ScheduledExecutorService} 034 * and adding extended trigger capabilities. 035 * 036 * <p>This interface is roughly equivalent to a JSR-236 037 * {@code ManagedScheduledExecutorService} as supported in Java EE 6 038 * environments. However, at the time of the Spring 3.0 release, the 039 * JSR-236 interfaces have not been released in official form yet. 040 * 041 * @author Juergen Hoeller 042 * @since 3.0 043 * @see org.springframework.core.task.TaskExecutor 044 * @see java.util.concurrent.ScheduledExecutorService 045 * @see org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler 046 */ 047public interface TaskScheduler { 048 049 /** 050 * Schedule the given {@link Runnable}, invoking it whenever the trigger 051 * indicates a next execution time. 052 * <p>Execution will end once the scheduler shuts down or the returned 053 * {@link ScheduledFuture} gets cancelled. 054 * @param task the Runnable to execute whenever the trigger fires 055 * @param trigger an implementation of the {@link Trigger} interface, 056 * e.g. a {@link org.springframework.scheduling.support.CronTrigger} object 057 * wrapping a cron expression 058 * @return a {@link ScheduledFuture} representing pending completion of the task, 059 * or {@code null} if the given Trigger object never fires (i.e. returns 060 * {@code null} from {@link Trigger#nextExecutionTime}) 061 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 062 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 063 * @see org.springframework.scheduling.support.CronTrigger 064 */ 065 ScheduledFuture<?> schedule(Runnable task, Trigger trigger); 066 067 /** 068 * Schedule the given {@link Runnable}, invoking it at the specified execution time. 069 * <p>Execution will end once the scheduler shuts down or the returned 070 * {@link ScheduledFuture} gets cancelled. 071 * @param task the Runnable to execute whenever the trigger fires 072 * @param startTime the desired execution time for the task 073 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible) 074 * @return a {@link ScheduledFuture} representing pending completion of the task 075 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 076 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 077 */ 078 ScheduledFuture<?> schedule(Runnable task, Date startTime); 079 080 /** 081 * Schedule the given {@link Runnable}, invoking it at the specified execution time 082 * and subsequently with the given period. 083 * <p>Execution will end once the scheduler shuts down or the returned 084 * {@link ScheduledFuture} gets cancelled. 085 * @param task the Runnable to execute whenever the trigger fires 086 * @param startTime the desired first execution time for the task 087 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible) 088 * @param period the interval between successive executions of the task (in milliseconds) 089 * @return a {@link ScheduledFuture} representing pending completion of the task 090 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 091 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 092 */ 093 ScheduledFuture<?> scheduleAtFixedRate(Runnable task, Date startTime, long period); 094 095 /** 096 * Schedule the given {@link Runnable}, starting as soon as possible and 097 * invoking it with the given period. 098 * <p>Execution will end once the scheduler shuts down or the returned 099 * {@link ScheduledFuture} gets cancelled. 100 * @param task the Runnable to execute whenever the trigger fires 101 * @param period the interval between successive executions of the task (in milliseconds) 102 * @return a {@link ScheduledFuture} representing pending completion of the task 103 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 104 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 105 */ 106 ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long period); 107 108 /** 109 * Schedule the given {@link Runnable}, invoking it at the specified execution time 110 * and subsequently with the given delay between the completion of one execution 111 * and the start of the next. 112 * <p>Execution will end once the scheduler shuts down or the returned 113 * {@link ScheduledFuture} gets cancelled. 114 * @param task the Runnable to execute whenever the trigger fires 115 * @param startTime the desired first execution time for the task 116 * (if this is in the past, the task will be executed immediately, i.e. as soon as possible) 117 * @param delay the delay between the completion of one execution and the start 118 * of the next (in milliseconds) 119 * @return a {@link ScheduledFuture} representing pending completion of the task 120 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 121 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 122 */ 123 ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, Date startTime, long delay); 124 125 /** 126 * Schedule the given {@link Runnable}, starting as soon as possible and 127 * invoking it with the given delay between the completion of one execution 128 * and the start of the next. 129 * <p>Execution will end once the scheduler shuts down or the returned 130 * {@link ScheduledFuture} gets cancelled. 131 * @param task the Runnable to execute whenever the trigger fires 132 * @param delay the interval between successive executions of the task (in milliseconds) 133 * @return a {@link ScheduledFuture} representing pending completion of the task 134 * @throws org.springframework.core.task.TaskRejectedException if the given task was not accepted 135 * for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress) 136 */ 137 ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long delay); 138 139}