Polish @EnableScheduling Javadoc

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

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

@@ -21,14 +21,136 @@ import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.concurrent.Executor;
 
+import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Import;
+import org.springframework.scheduling.Trigger;
+import org.springframework.scheduling.config.ScheduledTaskRegistrar;
 
 /**
- * Enables Spring's scheduled task execution capability.
+ * Enables Spring's scheduled task execution capability, similar to
+ * functionality found in Spring's {@code <task:*>} XML namespace. To be used
+ * on @{@link Configuration} classes as follows:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;EnableScheduling
+ * public class AppConfig {
+ *     // various &#064;Bean definitions
+ * }</pre>
+ *
+ * This enables detection of @{@link Scheduled} annotations on any Spring-managed
+ * bean in the container.  For example, given a class {@code MyTask}
+ *
+ * <pre class="code">
+ * package com.myco.tasks;
+ *
+ * public class MyTask {
+ *     &#064;Scheduled(fixedRate=1000)
+ *     public void work() {
+ *         // task execution logic
+ *     }
+ * }</pre>
+ *
+ * the following configuration would ensure that {@code MyTask.work()} is called
+ * once every 1000 ms:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;EnableScheduling
+ * public class AppConfig {
+ *     &#064;Bean
+ *     public MyTask task() {
+ *         return new MyTask();
+ *     }
+ * }</pre>
+ *
+ * Alternatively, if {@code MyTask} were annotated with {@code @Component}, the
+ * following configuration would ensure that its {@code @Scheduled} method is
+ * invoked at the desired interval:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;ComponentScan(basePackages="com.myco.tasks")
+ * public class AppConfig {
+ * }</pre>
+ *
+ * Methods annotated with {@code @Scheduled} may even be declared directly within
+ * {@code @Configuration} classes:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;EnableScheduling
+ * public class AppConfig {
+ *     &#064;Scheduled(fixedRate=1000)
+ *     public void work() {
+ *         // task execution logic
+ *     }
+ * }</pre>
+ *
+ * In all of the above scenarios, a default single-threaded task executor is used.
+ * When more control is desired, a {@code @Configuration} class may implement
+ * {@link SchedulingConfigurer}. This allows access to the underlying
+ * {@link ScheduledTaskRegistrar} instance. For example, the following example
+ * demonstrates how to customize the {@link Executor} used to execute scheduled
+ * tasks:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;EnableScheduling
+ * public class AppConfig implements SchedulingConfigurer {
+ *     &#064;Override
+ *     public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
+ *         taskRegistrar.setScheduler(taskExecutor());
+ *     }
+ *
+ *     &#064;Bean
+ *     public Executor taskExecutor() {
+ *         return Executors.newScheduledThreadPool(100);
+ *     }
+ * }</pre>
+ *
+ * Implementing {@code SchedulingConfigurer} also allows for fine-grained
+ * control over task registration via the {@code ScheduledTaskRegistrar}.
+ * For example, the following configures the execution of a particular bean
+ * method per a custom {@code Trigger} implementation:
+ *
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;EnableScheduling
+ * public class AppConfig implements SchedulingConfigurer {
+ *     &#064;Override
+ *     public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
+ *         taskRegistrar.setScheduler(taskExecutor());
+ *         taskRegistrar.addTriggerTask(
+ *         addTriggerTask(
+ *             new Runnable() {
+ *                 task().work();
+ *             },
+ *             new CustomTrigger()
+ *         );
+ *     }
+ *
+ *     &#064;Bean
+ *     public Executor taskExecutor() {
+ *         return Executors.newScheduledThreadPool(100);
+ *     }
+ *
+ *     &#064;Bean
+ *     public MyTask task() {
+ *         return new MyTask();
+ *     }
+ * }</pre>
  *
  * @author Chris Beams
  * @since 3.1
+ * @see Scheduled
+ * @see SchedulingConfiguration
+ * @see SchedulingConfigurer
+ * @see ScheduledTaskRegistrar
+ * @see Trigger
+ * @see ScheduledAnnotationBeanPostProcessor
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -32,6 +32,7 @@ import org.springframework.context.event.ContextRefreshedEvent;
 import org.springframework.core.Ordered;
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.scheduling.TaskScheduler;
+import org.springframework.scheduling.Trigger;
 import org.springframework.scheduling.config.ScheduledTaskRegistrar;
 import org.springframework.scheduling.support.ScheduledMethodRunnable;
 import org.springframework.util.Assert;
@@ -40,15 +41,25 @@ import org.springframework.util.ReflectionUtils.MethodCallback;
 import org.springframework.util.StringValueResolver;
 
 /**
- * Bean post-processor that registers methods annotated with {@link Scheduled @Scheduled}
+ * Bean post-processor that registers methods annotated with @{@link Scheduled}
  * to be invoked by a {@link org.springframework.scheduling.TaskScheduler} according
  * to the "fixedRate", "fixedDelay", or "cron" expression provided via the annotation.
  *
+ * <p>This post-processor is automatically registered by Spring's
+ * {@code <task:annotation-driven>} XML element, and also by the @{@link EnableScheduling}
+ * annotation.
+ *
+ * <p>Auto-detects any {@link SchedulingConfigurer} instances in the container,
+ * allowing for customization of the scheduler to be used or for fine-grained control
+ * over task registration (e.g. registration of {@link Trigger} tasks.
+ * See @{@link EnableScheduling} Javadoc for complete usage details.
+ *
  * @author Mark Fisher
  * @author Juergen Hoeller
  * @author Chris Beams
  * @since 3.0
  * @see Scheduled
+ * @see EnableScheduling
  * @see SchedulingConfigurer
  * @see org.springframework.scheduling.TaskScheduler
  * @see org.springframework.scheduling.config.ScheduledTaskRegistrar

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

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