Polish @EnableScheduling Javadoc and related XSD

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4413 50f2f4bb-b051-0410-bef5-90022cba6387

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/EnableScheduling.java

@@ -122,26 +122,43 @@ import org.springframework.scheduling.config.ScheduledTaskRegistrar;
  * public class AppConfig implements SchedulingConfigurer {
  *     @Override
  *     public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
- *         taskRegistrar.setScheduler(taskExecutor());
+ *         taskRegistrar.setScheduler(taskScheduler());
  *         taskRegistrar.addTriggerTask(
  *             new Runnable() {
- *                 task().work();
+ *                 myTask().work();
  *             },
  *             new CustomTrigger()
  *         );
  *     }
  *
  *     @Bean
- *     public Executor taskExecutor() {
+ *     public Executor taskScheduler() {
- *         return Executors.newScheduledThreadPool(100);
+ *         return Executors.newScheduledThreadPool(42);
  *     }
  *
  *     @Bean
- *     public MyTask task() {
+ *     public MyTask myTask() {
  *         return new MyTask();
  *     }
  * }</pre>
  *
+ * <p>For reference, the example above can be compared to the following Spring XML
+ * configuration:
+ * <pre class="code">
+ * {@code
+ * <beans>
+ *     <task:annotation-config scheduler="taskScheduler"/>
+ *     <task:scheduler id="taskScheduler" pool-size="42"/>
+ *     <task:scheduled ref="myTask" method="work" fixed-rate="1000"/>
+ *     <bean id="myTask" class="com.foo.MyAsyncBean"/>
+ * </beans>
+ * }</pre>
+ * the examples are equivalent save that in XML a <em>fixed-rate</em> period is used
+ * instead of a custom <em>{@code Trigger}</em> implementation; this is because the
+ * {@code task:} namespace {@code scheduled} cannot easily expose such support. This is
+ * but one demonstration how the code-based approach allows for maximum configurability
+ * through direct access to actual componentry.<p>
+ *
  * @author Chris Beams
  * @since 3.1
  * @see Scheduled

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/SchedulingConfiguration.java

@@ -23,12 +23,13 @@ import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Role;
 
 /**
- * Configures a {@link ScheduledAnnotationBeanPostProcessor} bean capable of
+ * {@code @Configuration} class that registers a {@link
- * processing Spring's @{@link Scheduled} annotation.
+ * ScheduledAnnotationBeanPostProcessor} bean capable of processing Spring's @{@link
+ * Scheduled} annotation.
  *
- * <p>This {@code @Configuration} class is automatically imported when using
+ * <p>This configuration class is automatically imported when using the @{@link
- * the @{@link EnableScheduling} annotation.  See {@code @EnableScheduling}
+ * EnableScheduling} annotation.  See {@code @EnableScheduling} Javadoc for complete usage
- * Javadoc for complete usage details.
+ * details.
  *
  * @author Chris Beams
  * @since 3.1

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

@@ -18,6 +18,21 @@ package org.springframework.scheduling.annotation;
 
 import org.springframework.scheduling.config.ScheduledTaskRegistrar;
 
+/**
+ * Interface to be implemented by @{@link org.springframework.context.annotation.Configuration}
+ * classes annotated with @{@link EnableScheduling} that wish to register scheduled tasks
+ * in a <em>programmatic</em> fashion as opposed to the <em>declarative</em> approach of
+ * using the @{@link Scheduled} annotation. For example, this may be necessary when
+ * implementing {@link org.springframework.scheduling.Trigger Trigger}-based tasks, which
+ * are not supported by the {@code @Scheduled} annotation.
+ *
+ * <p>See @{@link EnableScheduling} for detailed usage examples.
+ *
+ * @author Chris Beams
+ * @since 3.1
+ * @see EnableScheduling
+ * @see ScheduledTaskRegistrar
+ */
 public interface SchedulingConfigurer {
 
 	void configureTasks(ScheduledTaskRegistrar taskRegistrar);

org.springframework.context/src/main/java/org/springframework/scheduling/config/ScheduledTaskRegistrar.java

@@ -36,8 +36,16 @@ import org.springframework.util.Assert;
  * Helper bean for registering tasks with a {@link TaskScheduler},
  * typically using cron expressions.
  *
+ * <p>As of Spring 3.1, {@code ScheduledTaskRegistrar} has a more prominent user-facing
+ * role when used in conjunction with the @{@link
+ * org.springframework.scheduling.annotation.EnableAsync EnableAsync} annotation and its
+ * {@link org.springframework.scheduling.annotation.SchedulingConfigurer
+ * SchedulingConfigurer} callback interface.
+ *
  * @author Juergen Hoeller
  * @since 3.0
+ * @see org.springframework.scheduling.annotation.EnableAsync
+ * @see org.springframework.scheduling.annotation.SchedulingConfigurer
  */
 public class ScheduledTaskRegistrar implements InitializingBean, DisposableBean {
 
@@ -53,7 +61,7 @@ public class ScheduledTaskRegistrar implements InitializingBean, DisposableBean
 
 	private Map<Runnable, Long> fixedDelayTasks;
 
-	private final Set<ScheduledFuture> scheduledFutures = new LinkedHashSet<ScheduledFuture>();
+	private final Set<ScheduledFuture<?>> scheduledFutures = new LinkedHashSet<ScheduledFuture<?>>();
 
 
 	/**
@@ -194,7 +202,7 @@ public class ScheduledTaskRegistrar implements InitializingBean, DisposableBean
 
 
 	public void destroy() {
-		for (ScheduledFuture future : this.scheduledFutures) {
+		for (ScheduledFuture<?> future : this.scheduledFutures) {
 			future.cancel(true);
 		}
 		if (this.localExecutor != null) {

org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd

@@ -55,7 +55,9 @@
 	<xsd:element name="scheduler">
 		<xsd:annotation>
 			<xsd:documentation><![CDATA[
-	Defines a ThreadPoolTaskScheduler instance with configurable pool size.
+	Defines a ThreadPoolTaskScheduler instance with configurable pool size. See Javadoc
+	for the org.springframework.scheduling.annotation.EnableScheduling annotation for
+	information on a code-based alternative to this XML element.
 			]]></xsd:documentation>
 		</xsd:annotation>
 		<xsd:complexType>