Document repeatable annotation semantics for @scheduled

Closes gh-23959
spring-projects · Jul 14, 2023 · e303916 · e303916
1 parent 75f5dac
commit e303916
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 3 deletions.
diff --git a/framework-docs/modules/ROOT/pages/integration/scheduling.adoc b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc
@@ -380,6 +380,12 @@ Notice that the methods to be scheduled must have void returns and must not acce
 arguments. If the method needs to interact with other objects from the application
 context, those would typically have been provided through dependency injection.
 
+`@Scheduled` can be used as a repeatable annotation. If several scheduled declarations
+are found on the same method, each of them will be processed independently, with a
+separate trigger firing for each of them. As a consequence, such co-located schedules
+may overlap and execute multiple times in parallel or in immediate succession.
+Please make sure that your specified cron expressions etc do not accidentally overlap.
+
 [NOTE]
 ====
 As of Spring Framework 4.3, `@Scheduled` methods are supported on beans of any scope.

diff --git a/spring-context/src/main/java/org/springframework/scheduling/annotation/Scheduled.java b/spring-context/src/main/java/org/springframework/scheduling/annotation/Scheduled.java
@@ -29,8 +29,8 @@
 
 /**
  * Annotation that marks a method to be scheduled. Exactly one of the
- * {@link #cron}, {@link #fixedDelay}, or {@link #fixedRate} attributes must be
- * specified.
+ * {@link #cron}, {@link #fixedDelay}, or {@link #fixedRate} attributes
+ * must be specified.
  *
  * <p>The annotated method must expect no arguments. It will typically have
  * a {@code void} return type; if not, the returned value will be ignored
@@ -42,7 +42,10 @@
  * XML element or {@link EnableScheduling @EnableScheduling} annotation.
  *
  * <p>This annotation can be used as a <em>{@linkplain Repeatable repeatable}</em>
- * annotation.
+ * annotation. If several scheduled declarations are found on the same method,
+ * each of them will be processed independently, with a separate trigger firing
+ * for each of them. As a consequence, such co-located schedules may overlap
+ * and execute multiple times in parallel or in immediate succession.
  *
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em> with attribute overrides.