001/*
002 * Copyright 2002-2017 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.support;
018
019import java.util.Date;
020import java.util.concurrent.TimeUnit;
021
022import org.springframework.scheduling.Trigger;
023import org.springframework.scheduling.TriggerContext;
024import org.springframework.util.Assert;
025
026/**
027 * A trigger for periodic task execution. The period may be applied as either
028 * fixed-rate or fixed-delay, and an initial delay value may also be configured.
029 * The default initial delay is 0, and the default behavior is fixed-delay
030 * (i.e. the interval between successive executions is measured from each
031 * <emphasis>completion</emphasis> time). To measure the interval between the
032 * scheduled <emphasis>start</emphasis> time of each execution instead, set the
033 * 'fixedRate' property to {@code true}.
034 *
035 * <p>Note that the TaskScheduler interface already defines methods for scheduling
036 * tasks at fixed-rate or with fixed-delay. Both also support an optional value
037 * for the initial delay. Those methods should be used directly whenever
038 * possible. The value of this Trigger implementation is that it can be used
039 * within components that rely on the Trigger abstraction. For example, it may
040 * be convenient to allow periodic triggers, cron-based triggers, and even
041 * custom Trigger implementations to be used interchangeably.
042 *
043 * @author Mark Fisher
044 * @since 3.0
045 */
046public class PeriodicTrigger implements Trigger {
047
048        private final long period;
049
050        private final TimeUnit timeUnit;
051
052        private volatile long initialDelay = 0;
053
054        private volatile boolean fixedRate = false;
055
056
057        /**
058         * Create a trigger with the given period in milliseconds.
059         */
060        public PeriodicTrigger(long period) {
061                this(period, null);
062        }
063
064        /**
065         * Create a trigger with the given period and time unit. The time unit will
066         * apply not only to the period but also to any 'initialDelay' value, if
067         * configured on this Trigger later via {@link #setInitialDelay(long)}.
068         */
069        public PeriodicTrigger(long period, TimeUnit timeUnit) {
070                Assert.isTrue(period >= 0, "period must not be negative");
071                this.timeUnit = (timeUnit != null ? timeUnit : TimeUnit.MILLISECONDS);
072                this.period = this.timeUnit.toMillis(period);
073        }
074
075
076        /**
077         * Specify the delay for the initial execution. It will be evaluated in
078         * terms of this trigger's {@link TimeUnit}. If no time unit was explicitly
079         * provided upon instantiation, the default is milliseconds.
080         */
081        public void setInitialDelay(long initialDelay) {
082                this.initialDelay = this.timeUnit.toMillis(initialDelay);
083        }
084
085        /**
086         * Specify whether the periodic interval should be measured between the
087         * scheduled start times rather than between actual completion times.
088         * The latter, "fixed delay" behavior, is the default.
089         */
090        public void setFixedRate(boolean fixedRate) {
091                this.fixedRate = fixedRate;
092        }
093
094
095        /**
096         * Returns the time after which a task should run again.
097         */
098        @Override
099        public Date nextExecutionTime(TriggerContext triggerContext) {
100                if (triggerContext.lastScheduledExecutionTime() == null) {
101                        return new Date(System.currentTimeMillis() + this.initialDelay);
102                }
103                else if (this.fixedRate) {
104                        return new Date(triggerContext.lastScheduledExecutionTime().getTime() + this.period);
105                }
106                return new Date(triggerContext.lastCompletionTime().getTime() + this.period);
107        }
108
109
110        @Override
111        public boolean equals(Object obj) {
112                if (this == obj) {
113                        return true;
114                }
115                if (!(obj instanceof PeriodicTrigger)) {
116                        return false;
117                }
118                PeriodicTrigger other = (PeriodicTrigger) obj;
119                return (this.fixedRate == other.fixedRate && this.initialDelay == other.initialDelay &&
120                                this.period == other.period);
121        }
122
123        @Override
124        public int hashCode() {
125                return (this.fixedRate ? 17 : 29) + (int) (37 * this.period) + (int) (41 * this.initialDelay);
126        }
127
128}