org.springframework.scheduling.annotation Documentation Differences

This file contains all the changes in documentation in the package org.springframework.scheduling.annotation as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Enables Spring's asynchronous method execution capability, similar to functionality found in Spring's {@code } XML namespace. To be used on @Configuration classes as follows:

 @Configuration
 @EnableAsync
 public class AppConfig {
     @Bean
     public MyAsyncBean asyncBean() {
         return new MyAsyncBean();
     }
 }

where {@code MyAsyncBean} is a user-defined type with one or methods annotated with @Async (or any custom annotation specified by the .annotation() attribute).

The .mode() attribute controls how advice is applied; if the mode is AdviceMode.PROXY (the default), then the other attributes control the behavior of the proxying.

Note that if the #mode is set to AdviceMode.ASPECTJ, then the .proxyTargetClass() attribute is obsolete. Note also that in this case the {@code spring-aspects} module JAR must be present on the classpath.

By default, a SimpleAsyncTaskExecutor will be used to process async method invocations. To customize this behavior, implement AsyncConfigurer and provide your own Executor through the getExecutor() method.

 @Configuration
 @EnableAsync
 public class AppConfig implements AsyncConfigurer {

     @Bean
     public MyAsyncBean asyncBean() {
         return new MyAsyncBean();
     }

     @Override
     public Executor getAsyncExecutor() {
         ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
         executor.setCorePoolSize(7);
         executor.setMaxPoolSize(42);
         executor.setQueueCapacity(11);
         executor.setThreadNamePrefix("MyExecutor-");
         executor.initialize();
         return executor;
     }
 }

For reference, the example above can be compared to the following Spring XML configuration:

 {@code
 
     
     
     
 
 }

the examples are equivalent save the setting of the thread name prefix of the Executor; this is because the the {@code task:} namespace {@code executor} element does not expose such an attribute. This demonstrates how the code-based approach allows for maximum configurability through direct access to actual componentry.

Note: In the above example the {@code ThreadPoolTaskExecutor} is not a fully managed Spring Bean. Add the {@code @Bean} annotation to the {@code getAsyncExecutor()} method if you want a fully managed bean. In such circumstances it is no longer necessary to manually call the {@code executor.initialize()} method as this will be invoked automatically when the bean is initialized. @author Chris Beams @since 3.1 @see Async @see AsyncConfigurer @see AsyncConfigurationSelector

Enables Spring's scheduled task execution capability, similar to functionality found in Spring's {@code } XML namespace. To be used on @Configuration classes as follows:

 @Configuration
 @EnableScheduling
 public class AppConfig {
     // various @Bean definitions
 }

This enables detection of @Scheduled annotations on any Spring-managed bean in the container. For example, given a class {@code MyTask}

 package com.myco.tasks;

 public class MyTask {
     @Scheduled(fixedRate=1000)
     public void work() {
         // task execution logic
     }
 }

the following configuration would ensure that {@code MyTask.work()} is called once every 1000 ms:

 @Configuration
 @EnableScheduling
 public class AppConfig {
     @Bean
     public MyTask task() {
         return new MyTask();
     }
 }

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:

 @Configuration
 @ComponentScan(basePackages="com.myco.tasks")
 public class AppConfig {
 }

Methods annotated with {@code @Scheduled} may even be declared directly within {@code @Configuration} classes:

 @Configuration
 @EnableScheduling
 public class AppConfig {
     @Scheduled(fixedRate=1000)
     public void work() {
         // task execution logic
     }
 }

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 SchedulingConfigurer. This allows access to the underlying ScheduledTaskRegistrar instance. For example, the following example demonstrates how to customize the Executor used to execute scheduled tasks:

 @Configuration
 @EnableScheduling
 public class AppConfig implements SchedulingConfigurer {
     @Override
     public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
         taskRegistrar.setScheduler(taskExecutor());
     }

     @Bean(destroyMethod="shutdown")
     public Executor taskExecutor() {
         return Executors.newScheduledThreadPool(100);
     }
 }

Note in the example above the use of {@code @Bean(destroyMethod="shutdown")}. This ensures that the task executor is properly shut down when the Spring application context itself is closed. 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:

 @Configuration
 @EnableScheduling
 public class AppConfig implements SchedulingConfigurer {
     @Override
     public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
         taskRegistrar.setScheduler(taskScheduler());
         taskRegistrar.addTriggerTask(
             new Runnable() {
                 public void run() {
                     myTask().work();
                 }
             },
             new CustomTrigger()
         );
     }

     @Bean(destroyMethod="shutdown")
     public Executor taskScheduler() {
         return Executors.newScheduledThreadPool(42);
     }

     @Bean
     public MyTask myTask() {
         return new MyTask();
     }
 }

For reference, the example above can be compared to the following Spring XML configuration:

 {@code
 
     
     
     
     
 
 }

the examples are equivalent save that in XML a fixed-rate period is used instead of a custom {@code Trigger} 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.

@author Chris Beams @since 3.1 @see Scheduled @see SchedulingConfiguration @see SchedulingConfigurer @see ScheduledTaskRegistrar @see Trigger @see ScheduledAnnotationBeanPostProcessor