From 4afcddcbc7b959e60ea0fb1049c44678dcd6dbad Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Tue, 4 Aug 2009 15:58:54 +0000 Subject: [PATCH] added PeriodicTrigger implementation --- .../scheduling/support/PeriodicTrigger.java | 128 +++++++++ .../support/PeriodicTriggerTests.java | 270 ++++++++++++++++++ 2 files changed, 398 insertions(+) create mode 100644 org.springframework.context/src/main/java/org/springframework/scheduling/support/PeriodicTrigger.java create mode 100644 org.springframework.context/src/test/java/org/springframework/scheduling/support/PeriodicTriggerTests.java diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/support/PeriodicTrigger.java b/org.springframework.context/src/main/java/org/springframework/scheduling/support/PeriodicTrigger.java new file mode 100644 index 0000000000..fe45ac2121 --- /dev/null +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/support/PeriodicTrigger.java @@ -0,0 +1,128 @@ +/* + * Copyright 2002-2009 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.scheduling.support; + +import java.util.Date; +import java.util.concurrent.TimeUnit; + +import org.springframework.scheduling.Trigger; +import org.springframework.scheduling.TriggerContext; +import org.springframework.util.Assert; + +/** + * A trigger for periodic task execution. The period may be applied as either + * fixed-rate or fixed-delay, and an initial delay value may also be configured. + * The default initial delay is 0, and the default behavior is fixed-delay + * (i.e. the interval between successive executions is measured from each + * completion time). To measure the interval between the + * scheduled start time of each execution instead, set the + * 'fixedRate' property to true. + *

+ * Note that the TaskScheduler interface already defines methods for scheduling + * tasks at fixed-rate or with fixed-delay. Both also support an optional value + * for the initial delay. Those methods should be used directly whenever + * possible. The value of this Trigger implementation is that it can be used + * within components that rely on the Trigger abstraction. For example, it may + * be convenient to allow periodic triggers, cron-based triggers, and even + * custom Trigger implementations to be used interchangeably. + * + * @author Mark Fisher + * @since 3.0 + */ +public class PeriodicTrigger implements Trigger { + + private final long period; + + private final TimeUnit timeUnit; + + private volatile long initialDelay = 0; + + private volatile boolean fixedRate = false; + + + /** + * Create a trigger with the given period in milliseconds. + */ + public PeriodicTrigger(long period) { + this(period, null); + } + + /** + * Create a trigger with the given period and time unit. The time unit will + * apply not only to the period but also to any 'initialDelay' value, if + * configured on this Trigger later via {@link #setInitialDelay(long)}. + */ + public PeriodicTrigger(long period, TimeUnit timeUnit) { + Assert.isTrue(period >= 0, "period must not be negative"); + this.timeUnit = (timeUnit != null) ? timeUnit : TimeUnit.MILLISECONDS; + this.period = this.timeUnit.toMillis(period); + } + + + /** + * Specify the delay for the initial execution. It will be evaluated in + * terms of this trigger's {@link TimeUnit}. If no time unit was explicitly + * provided upon instantiation, the default is milliseconds. + */ + public void setInitialDelay(long initialDelay) { + this.initialDelay = this.timeUnit.toMillis(initialDelay); + } + + /** + * Specify whether the periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * The latter, "fixed delay" behavior, is the default. + */ + public void setFixedRate(boolean fixedRate) { + this.fixedRate = fixedRate; + } + + /** + * Returns the time after which a task should run again. + */ + public Date nextExecutionTime(TriggerContext triggerContext) { + if (triggerContext.lastScheduledExecutionTime() == null) { + return new Date(System.currentTimeMillis() + this.initialDelay); + } + else if (this.fixedRate) { + return new Date(triggerContext.lastScheduledExecutionTime().getTime() + this.period); + } + return new Date(triggerContext.lastCompletionTime().getTime() + this.period); + } + + @Override + public boolean equals(Object obj) { + if (this == obj) { + return true; + } + if (!(obj instanceof PeriodicTrigger)) { + return false; + } + PeriodicTrigger other = (PeriodicTrigger) obj; + return this.fixedRate == other.fixedRate + && this.initialDelay == other.initialDelay + && this.period == other.period; + } + + @Override + public int hashCode() { + return (this.fixedRate ? 17 : 29) + + (int) (37 * this.period) + + (int) (41 * this.initialDelay); + } + +} diff --git a/org.springframework.context/src/test/java/org/springframework/scheduling/support/PeriodicTriggerTests.java b/org.springframework.context/src/test/java/org/springframework/scheduling/support/PeriodicTriggerTests.java new file mode 100644 index 0000000000..c0faca5e68 --- /dev/null +++ b/org.springframework.context/src/test/java/org/springframework/scheduling/support/PeriodicTriggerTests.java @@ -0,0 +1,270 @@ +/* + * Copyright 2002-2009 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.scheduling.support; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertTrue; + +import java.util.Date; +import java.util.concurrent.TimeUnit; + +import org.junit.Test; + +import org.springframework.scheduling.TriggerContext; +import org.springframework.util.NumberUtils; + +/** + * @author Mark Fisher + * @since 3.0 + */ +public class PeriodicTriggerTests { + + @Test + public void fixedDelayFirstExecution() { + Date now = new Date(); + PeriodicTrigger trigger = new PeriodicTrigger(5000); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertNegligibleDifference(now, next); + } + + @Test + public void fixedDelayWithInitialDelayFirstExecution() { + Date now = new Date(); + long period = 5000; + long initialDelay = 30000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertApproximateDifference(now, next, initialDelay); + } + + @Test + public void fixedDelayWithTimeUnitFirstExecution() { + Date now = new Date(); + PeriodicTrigger trigger = new PeriodicTrigger(5, TimeUnit.SECONDS); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertNegligibleDifference(now, next); + } + + @Test + public void fixedDelayWithTimeUnitAndInitialDelayFirstExecution() { + Date now = new Date(); + long period = 5; + long initialDelay = 30; + PeriodicTrigger trigger = new PeriodicTrigger(period, TimeUnit.SECONDS); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertApproximateDifference(now, next, initialDelay * 1000); + } + + @Test + public void fixedDelaySubsequentExecution() { + Date now = new Date(); + long period = 5000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, period + 3000); + } + + @Test + public void fixedDelayWithInitialDelaySubsequentExecution() { + Date now = new Date(); + long period = 5000; + long initialDelay = 30000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, period + 3000); + } + + @Test + public void fixedDelayWithTimeUnitSubsequentExecution() { + Date now = new Date(); + long period = 5; + PeriodicTrigger trigger = new PeriodicTrigger(period, TimeUnit.SECONDS); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, (period * 1000) + 3000); + } + + @Test + public void fixedRateFirstExecution() { + Date now = new Date(); + PeriodicTrigger trigger = new PeriodicTrigger(5000); + trigger.setFixedRate(true); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertNegligibleDifference(now, next); + } + + @Test + public void fixedRateWithTimeUnitFirstExecution() { + Date now = new Date(); + PeriodicTrigger trigger = new PeriodicTrigger(5, TimeUnit.SECONDS); + trigger.setFixedRate(true); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertNegligibleDifference(now, next); + } + + @Test + public void fixedRateWithInitialDelayFirstExecution() { + Date now = new Date(); + long period = 5000; + long initialDelay = 30000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + trigger.setFixedRate(true); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertApproximateDifference(now, next, initialDelay); + } + + @Test + public void fixedRateWithTimeUnitAndInitialDelayFirstExecution() { + Date now = new Date(); + long period = 5; + long initialDelay = 30; + PeriodicTrigger trigger = new PeriodicTrigger(period, TimeUnit.MINUTES); + trigger.setFixedRate(true); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(null, null, null)); + assertApproximateDifference(now, next, (initialDelay * 60 * 1000)); + } + + @Test + public void fixedRateSubsequentExecution() { + Date now = new Date(); + long period = 5000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + trigger.setFixedRate(true); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, period); + } + + @Test + public void fixedRateWithInitialDelaySubsequentExecution() { + Date now = new Date(); + long period = 5000; + long initialDelay = 30000; + PeriodicTrigger trigger = new PeriodicTrigger(period); + trigger.setFixedRate(true); + trigger.setInitialDelay(initialDelay); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, period); + } + + @Test + public void fixedRateWithTimeUnitSubsequentExecution() { + Date now = new Date(); + long period = 5; + PeriodicTrigger trigger = new PeriodicTrigger(period, TimeUnit.HOURS); + trigger.setFixedRate(true); + Date next = trigger.nextExecutionTime(context(now, 500, 3000)); + assertApproximateDifference(now, next, (period * 60 * 60 * 1000)); + } + + @Test + public void equalsVerification() { + PeriodicTrigger trigger1 = new PeriodicTrigger(3000); + PeriodicTrigger trigger2 = new PeriodicTrigger(3000); + assertFalse(trigger1.equals(new String("not a trigger"))); + assertFalse(trigger1.equals(null)); + assertEquals(trigger1, trigger1); + assertEquals(trigger2, trigger2); + assertEquals(trigger1, trigger2); + trigger2.setInitialDelay(1234); + assertFalse(trigger1.equals(trigger2)); + assertFalse(trigger2.equals(trigger1)); + trigger1.setInitialDelay(1234); + assertEquals(trigger1, trigger2); + trigger2.setFixedRate(true); + assertFalse(trigger1.equals(trigger2)); + assertFalse(trigger2.equals(trigger1)); + trigger1.setFixedRate(true); + assertEquals(trigger1, trigger2); + PeriodicTrigger trigger3 = new PeriodicTrigger(3, TimeUnit.SECONDS); + trigger3.setInitialDelay(7); + trigger3.setFixedRate(true); + assertFalse(trigger1.equals(trigger3)); + assertFalse(trigger3.equals(trigger1)); + trigger1.setInitialDelay(7000); + assertEquals(trigger1, trigger3); + } + + + // utility methods + + private static void assertNegligibleDifference(Date d1, Date d2) { + long diff = Math.abs(d1.getTime() - d2.getTime()); + assertTrue("difference exceeds threshold: " + diff, diff < 100); + } + + private static void assertApproximateDifference(Date lesser, Date greater, long expected) { + long diff = greater.getTime() - lesser.getTime(); + long variance = Math.abs(expected - diff); + assertTrue("expected approximate difference of " + expected + + ", but actual difference was " + diff, variance < 100); + } + + private static TriggerContext context(Object scheduled, Object actual, Object completion) { + return new TestTriggerContext(asDate(scheduled), asDate(actual), asDate(completion)); + } + + private static Date asDate(Object o) { + if (o == null) { + return null; + } + if (o instanceof Date) { + return (Date) o; + } + if (o instanceof Number) { + return new Date(System.currentTimeMillis() + + NumberUtils.convertNumberToTargetClass((Number) o, Long.class)); + } + throw new IllegalArgumentException( + "expected Date or Number, but actual type was: " + o.getClass()); + } + + + // helper class + + private static class TestTriggerContext implements TriggerContext { + + private final Date scheduled; + + private final Date actual; + + private final Date completion; + + TestTriggerContext(Date scheduled, Date actual, Date completion) { + this.scheduled = scheduled; + this.actual = actual; + this.completion = completion; + } + + public Date lastActualExecutionTime() { + return this.actual; + } + + public Date lastCompletionTime() { + return this.completion; + } + + public Date lastScheduledExecutionTime() { + return this.scheduled; + } + } + +}