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}