Package org.springframework.scheduling.annotation

Annotation Interface Scheduled

@Target({METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Documented @Repeatable(Schedules.class) @Reflective public @interface Scheduled
Annotation that marks a method to be scheduled. For periodic tasks, exactly one of the cron(), fixedDelay(), or fixedRate() attributes must be specified, and additionally an optional initialDelay(). For a one-time task, it is sufficient to just specify an initialDelay().

The annotated method must not accept arguments. It will typically have a void return type; if not, the returned value will be ignored when called through the scheduler.

Methods that return a reactive Publisher or a type which can be adapted to Publisher by the default ReactiveAdapterRegistry are supported. The Publisher must support multiple subsequent subscriptions. The returned Publisher is only produced once, and the scheduling infrastructure then periodically subscribes to it according to configuration. Values emitted by the publisher are ignored. Errors are logged at WARN level, which doesn't prevent further iterations. If a fixed delay is configured, the subscription is blocked in order to respect the fixed delay semantics.

Kotlin suspending functions are also supported, provided the coroutine-reactor bridge (kotlinx.coroutine.reactor) is present at runtime. This bridge is used to adapt the suspending function to a Publisher which is treated the same way as in the reactive method case (see above).

Processing of @Scheduled annotations is performed by registering a ScheduledAnnotationBeanPostProcessor. This can be done manually or, more conveniently, through the <task:annotation-driven/> XML element or @EnableScheduling annotation.

This annotation 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.

This annotation may be used as a meta-annotation to create custom composed annotations with attribute overrides.

Since:
3.0
Author:
Mark Fisher, Juergen Hoeller, Dave Syer, Chris Beams, Victor Brown, Sam Brannen
See Also:

  • Field Details

    • CRON_DISABLED

      static final String CRON_DISABLED
      A special cron expression value that indicates a disabled trigger: "-".

      This is primarily meant for use with ${...} placeholders, allowing for external disabling of corresponding scheduled methods.

      Since:
      5.1
      See Also:

  • Element Details

    • cron

      String cron
      A cron-like expression, extending the usual UN*X definition to include triggers on the second, minute, hour, day of month, month, and day of week.

      For example, "0 * * * * MON-FRI" means once per minute on weekdays (at the top of the minute - the 0th second).

      The fields read from left to right are interpreted as follows.

      • second
      • minute
      • hour
      • day of month
      • month
      • day of week

      The special value "-" indicates a disabled cron trigger, primarily meant for externally specified values resolved by a ${...} placeholder.

      Returns:
      an expression that can be parsed to a cron schedule
      See Also:
      Default:
      ""

    • zone

      String zone
      A time zone for which the cron expression will be resolved. By default, this attribute is the empty String (i.e. the scheduler's time zone will be used).
      Returns:
      a zone id accepted by TimeZone.getTimeZone(String), or an empty String to indicate the scheduler's default time zone
      Since:
      4.0
      See Also:
      Default:
      ""

    • fixedRate

      long fixedRate
      Execute the annotated method with a fixed period between invocations.

      The time unit is milliseconds by default but can be overridden via timeUnit().

      Returns:
      the period
      Default:
      -1L

    • fixedRateString

      String fixedRateString
      Execute the annotated method with a fixed period between invocations.

      The duration String can be in several formats:

      • a plain integer — which is interpreted to represent a duration in milliseconds by default unless overridden via timeUnit() (prefer using fixedDelay() in that case)
      • any of the known DurationFormat.Style: the ISO8601 style or the SIMPLE style — using the timeUnit() as fallback if the string doesn't contain an explicit unit
      • one of the above, with Spring-style "${...}" placeholders as well as SpEL expressions
      Returns:
      the period as a String value — for example a placeholder, or a java.time.Duration compliant value or a simple format compliant value
      Since:
      3.2.2
      See Also:
      Default:
      ""

    • fixedDelay

      long fixedDelay
      Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.

      The time unit is milliseconds by default but can be overridden via timeUnit().

      NOTE: With virtual threads, fixed rates and cron triggers are recommended over fixed delays. Fixed-delay tasks operate on a single scheduler thread with SimpleAsyncTaskScheduler.

      Returns:
      the delay
      Default:
      -1L

    • fixedDelayString

      String fixedDelayString
      Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.

      The duration String can be in several formats:

      • a plain integer — which is interpreted to represent a duration in milliseconds by default unless overridden via timeUnit() (prefer using fixedDelay() in that case)
      • any of the known DurationFormat.Style: the ISO8601 style or the SIMPLE style — using the timeUnit() as fallback if the string doesn't contain an explicit unit

      NOTE: With virtual threads, fixed rates and cron triggers are recommended over fixed delays. Fixed-delay tasks operate on a single scheduler thread with SimpleAsyncTaskScheduler.

      Returns:
      the delay as a String value — for example a placeholder, or a java.time.Duration compliant value or a simple format compliant value
      Since:
      3.2.2
      See Also:
      Default:
      ""

    • initialDelay

      long initialDelay
      Number of units of time to delay before the first execution of a fixedRate() or fixedDelay() task.

      The time unit is milliseconds by default but can be overridden via timeUnit().

      Returns:
      the initial
      Since:
      3.2
      Default:
      -1L

    • initialDelayString

      String initialDelayString
      Number of units of time to delay before the first execution of a fixedRate() or fixedDelay() task.

      The duration String can be in several formats:

      • a plain integer — which is interpreted to represent a duration in milliseconds by default unless overridden via timeUnit() (prefer using fixedDelay() in that case)
      • any of the known DurationFormat.Style: the ISO8601 style or the SIMPLE style — using the timeUnit() as fallback if the string doesn't contain an explicit unit
      • one of the above, with Spring-style "${...}" placeholders as well as SpEL expressions
      Returns:
      the initial delay as a String value — for example a placeholder, or a java.time.Duration compliant value or a simple format compliant value
      Since:
      3.2.2
      See Also:
      Default:
      ""

    • timeUnit

      TimeUnit timeUnit
      The TimeUnit to use for fixedDelay(), fixedDelayString(), fixedRate(), fixedRateString(), initialDelay(), and initialDelayString().

      Defaults to TimeUnit.MILLISECONDS.

      This attribute is ignored for cron expressions and for Duration values supplied via fixedDelayString(), fixedRateString(), or initialDelayString().

      Returns:
      the TimeUnit to use
      Since:
      5.3.10
      Default:
      MILLISECONDS

    • scheduler

      String scheduler
      A qualifier for determining a scheduler to run this scheduled method on.

      Defaults to an empty String, suggesting the default scheduler.

      May be used to determine the target scheduler to be used, matching the qualifier value (or the bean name) of a specific TaskScheduler or ScheduledExecutorService bean definition.

      Since:
      6.1
      See Also:
      Default:
      ""