Support initial delay attribute for scheduled tasks

java.util.concurrent's ScheduledExecutorService and its #schedule*
methods allow for an 'initialDelay' parameter in milliseconds.
Similarly, Spring's TaskExecutor abstraction allows for a concrete
'startTime' expressed as a Date. However, Spring's <task:scheduled> XML
element and @scheduled annotation have, to date, not allowed for an
initial delay parameter that can be propagated down to the underlying
TaskScheduler/ScheduledExecutorService.

This commit introduces initial-delay and #initialDelay attributes to
task:scheduled and @scheduled respectively, both indicating the number
of milliseconds to wait before the first invocation of the method in
question. Specifying a delay in this fashion is only valid in
conjunction with fixed-rate and fixed-delay tasks (i.e. not with cron
or trigger tasks).

The principal changes required to support these new attributes lie in
ScheduledTaskRegistrar, which previously supported registration of
tasks in the form of a Runnable and a Long parameter indicating (in the
case of fixed-rate and fixed-delay tasks), the interval with which the
task should be executed. In order to accommodate a third (and optional)
'initialDelay' parameter, the IntervalTask class has been added as a
holder for the Runnable to be executed, the interval in which to run
it, and the optional initial delay. For symmetry, a TriggerTask and
CronTask have also been added, the latter subclassing the former. And a
'Task' class has been added as a common ancestor for all the above.

One oddity of the implementation is in the naming of the new
setters in ScheduledTaskRegistrar. Prior to this commit, the setters
were named #setFixedDelayTasks, #setFixedRateTasks, etc, each accepting
a Map<Runnable, long>. In adding new setters for each task type, each
accepting a List<IntervalTask>, List<CronTask> etc, naturally the
approach would be to use method overloading and to introduce methods
of the same name but with differing parameter types. Unfortunately
however, Spring does not support injection against overloaded methods
(due to fundamental limitations of the underlying JDK Introspector).
This is not a problem when working with the ScheduledTaskRegistrar
directly, e.g. from within a @configuration class that implements
SchedulingConfigurer, but is a problem from the point of view of the
ScheduledTasksBeanDefinitionParser which parses the <task:scheduled>
element - here the ScheduledTaskRegistrar is treated as a Spring bean
and is thus subject to these limitations. The solution to this problem
was simply to avoid overloading altogether, thus the naming of the new
methods ending in "List", e.g. #setFixedDelayTasksList, etc. These
methods exist primarily for use by the BeanDefinitionParser and are
not really intended for use by application developers. The Javadoc for
each of the new methods makes note of this.

Issue: SPR-7022

Author: cbeams

spring-context/src/main/java/org/springframework/scheduling/annotation/Scheduled.java

@@ -37,6 +37,7 @@
  *
  * @author Mark Fisher
  * @author Dave Syer
+ * @author Chris Beams
  * @since 3.0
  * @see EnableScheduling
  * @see ScheduledAnnotationBeanPostProcessor
@@ -69,4 +70,12 @@
 	 */
 	long fixedRate() default -1;
 
+	/**
+	 * Number of milliseconds to delay before the first execution of a
+	 * {@link #fixedRate()} or {@link #fixedDelay()} task.
+	 * @return the initial delay in milliseconds
+	 * @since 3.2
+	 */
+	long initialDelay() default 0;
+
 }

spring-context/src/main/java/org/springframework/scheduling/annotation/ScheduledAnnotationBeanPostProcessor.java

@@ -34,6 +34,8 @@
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.scheduling.TaskScheduler;
 import org.springframework.scheduling.Trigger;
+import org.springframework.scheduling.config.CronTask;
+import org.springframework.scheduling.config.IntervalTask;
 import org.springframework.scheduling.config.ScheduledTaskRegistrar;
 import org.springframework.scheduling.support.ScheduledMethodRunnable;
 import org.springframework.util.Assert;
@@ -75,13 +77,7 @@ public class ScheduledAnnotationBeanPostProcessor
 
 	private ApplicationContext applicationContext;
 
-	private ScheduledTaskRegistrar registrar;
-
-	private final Map<Runnable, String> cronTasks = new HashMap<Runnable, String>();
-
-	private final Map<Runnable, Long> fixedDelayTasks = new HashMap<Runnable, Long>();
-
-	private final Map<Runnable, Long> fixedRateTasks = new HashMap<Runnable, Long>();
+	private final ScheduledTaskRegistrar registrar = new ScheduledTaskRegistrar();
 
 
 	/**
@@ -146,19 +142,20 @@ public void doWith(Method method) throws IllegalArgumentException, IllegalAccess
 						if (embeddedValueResolver != null) {
 							cron = embeddedValueResolver.resolveStringValue(cron);
 						}
-						cronTasks.put(runnable, cron);
+						registrar.addCronTask(new CronTask(runnable, cron));
 					}
+					long initialDelay = annotation.initialDelay();
 					long fixedDelay = annotation.fixedDelay();
 					if (fixedDelay >= 0) {
 						Assert.isTrue(!processedSchedule, errorMessage);
 						processedSchedule = true;
-						fixedDelayTasks.put(runnable, fixedDelay);
+						registrar.addFixedDelayTask(new IntervalTask(runnable, fixedDelay, initialDelay));
 					}
 					long fixedRate = annotation.fixedRate();
 					if (fixedRate >= 0) {
 						Assert.isTrue(!processedSchedule, errorMessage);
 						processedSchedule = true;
-						fixedRateTasks.put(runnable, fixedRate);
+						registrar.addFixedRateTask(new IntervalTask(runnable, fixedRate, initialDelay));
 					}
 					Assert.isTrue(processedSchedule, errorMessage);
 				}
@@ -175,16 +172,6 @@ public void onApplicationEvent(ContextRefreshedEvent event) {
 		Map<String, SchedulingConfigurer> configurers =
 				this.applicationContext.getBeansOfType(SchedulingConfigurer.class);
 
-		if (this.cronTasks.isEmpty() && this.fixedDelayTasks.isEmpty() &&
-				this.fixedRateTasks.isEmpty() && configurers.isEmpty()) {
-			return;
-		}
-
-		this.registrar = new ScheduledTaskRegistrar();
-		this.registrar.setCronTasks(this.cronTasks);
-		this.registrar.setFixedDelayTasks(this.fixedDelayTasks);
-		this.registrar.setFixedRateTasks(this.fixedRateTasks);
-
 		if (this.scheduler != null) {
 			this.registrar.setScheduler(this.scheduler);
 		}
@@ -193,7 +180,7 @@ public void onApplicationEvent(ContextRefreshedEvent event) {
 			configurer.configureTasks(this.registrar);
 		}
 
-		if (this.registrar.getScheduler() == null) {
+		if (this.registrar.hasTasks() && this.registrar.getScheduler() == null) {
 			Map<String, ? super Object> schedulers = new HashMap<String, Object>();
 			schedulers.putAll(applicationContext.getBeansOfType(TaskScheduler.class));
 			schedulers.putAll(applicationContext.getBeansOfType(ScheduledExecutorService.class));

spring-context/src/main/java/org/springframework/scheduling/annotation/SchedulingConfigurer.java

@@ -38,6 +38,12 @@
  */
 public interface SchedulingConfigurer {
 
+	/**
+	 * Callback allowing a {@link org.springframework.scheduling.TaskScheduler
+	 * TaskScheduler} and specific {@link org.springframework.scheduling.config.Task Task}
+	 * instances to be registered against the given the {@link ScheduledTaskRegistrar}
+	 * @param taskRegistrar the registrar to be configured.
+	 */
 	void configureTasks(ScheduledTaskRegistrar taskRegistrar);
 
 }

spring-context/src/main/java/org/springframework/scheduling/config/CronTask.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2002-2012 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.config;
+
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.scheduling.support.CronTrigger;
+
+/**
+ * {@link TriggerTask} implementation defining a {@code Runnable} to be executed according
+ * to a {@linkplain org.springframework.scheduling.support.CronSequenceGenerator standard
+ * cron expression}.
+ *
+ * @author Chris Beams
+ * @since 3.2
+ * @see Scheduled#cron()
+ * @see ScheduledTaskRegistrar#setCronTasksList(java.util.List)
+ * @see org.springframework.scheduling.TaskScheduler
+ */
+public class CronTask extends TriggerTask {
+
+	private String expression;
+
+
+	/**
+	 * Create a new {@code CronTask}.
+	 * @param runnable the underlying task to execute
+	 * @param expression cron expression defining when the task should be executed
+	 */
+	public CronTask(Runnable runnable, String expression) {
+		this(runnable, new CronTrigger(expression));
+	}
+
+	/**
+	 * Create a new {@code CronTask}.
+	 * @param runnable the underlying task to execute
+	 * @param cronTrigger the cron trigger defining when the task should be executed
+	 */
+	public CronTask(Runnable runnable, CronTrigger cronTrigger) {
+		super(runnable, cronTrigger);
+		this.expression = cronTrigger.getExpression();
+	}
+
+	public String getExpression() {
+		return expression;
+	}
+}

spring-context/src/main/java/org/springframework/scheduling/config/IntervalTask.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2002-2012 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.config;
+
+/**
+ * {@link Task} implementation defining a {@code Runnable} to be executed at a given
+ * millisecond interval which may be treated as fixed-rate or fixed-delay depending on
+ * context.
+ *
+ * @author Chris Beams
+ * @since 3.2
+ * @see org.springframework.scheduling.annotation.Scheduled#fixedRate()
+ * @see org.springframework.scheduling.annotation.Scheduled#fixedDelay()
+ * @see ScheduledTaskRegistrar#setFixedRateTasksList(java.util.List)
+ * @see ScheduledTaskRegistrar#setFixedDelayTasksList(java.util.List)
+ * @see org.springframework.scheduling.TaskScheduler
+ */
+public class IntervalTask extends Task {
+
+	private final long interval;
+
+	private final long initialDelay;
+
+
+	/**
+	 * Create a new {@code IntervalTask}.
+	 * @param runnable the underlying task to execute
+	 * @param interval how often in milliseconds the task should be executed
+	 * @param initialDelay initial delay before first execution of the task
+	 */
+	public IntervalTask(Runnable runnable, long interval, long initialDelay) {
+		super(runnable);
+		this.initialDelay = initialDelay;
+		this.interval = interval;
+	}
+
+	/**
+	 * Create a new {@code IntervalTask} with no initial delay.
+	 * @param runnable the underlying task to execute
+	 * @param interval how often in milliseconds the task should be executed
+	 */
+	public IntervalTask(Runnable runnable, long interval) {
+		this(runnable, interval, 0);
+	}
+
+
+	public long getInterval() {
+		return interval;
+	}
+
+	public long getInitialDelay() {
+		return initialDelay;
+	}
+}