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:
  - `EnableScheduling`
  - `ScheduledAnnotationBeanPostProcessor`
  - `Schedules`

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`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.
`long`
`fixedDelay`
Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.
`String`
`fixedDelayString`
Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.
`long`
`fixedRate`
Execute the annotated method with a fixed period between invocations.
`String`
`fixedRateString`
Execute the annotated method with a fixed period between invocations.
`long`
`initialDelay`
Number of units of time to delay before the first execution of a `fixedRate()` or `fixedDelay()` task.
`String`
`initialDelayString`
Number of units of time to delay before the first execution of a `fixedRate()` or `fixedDelay()` task.
`String`
`scheduler`
A qualifier for determining a scheduler to run this scheduled method on.
`TimeUnit`
`timeUnit`
The `TimeUnit` to use for `fixedDelay()`, `fixedDelayString()`, `fixedRate()`, `fixedRateString()`, `initialDelay()`, and `initialDelayString()`.
`String`
`zone`
A time zone for which the cron expression will be resolved.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`CRON_DISABLED`
A special cron expression value that indicates a disabled trigger: "-".

## 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:
  - `ScheduledTaskRegistrar.CRON_DISABLED`
  - Constant Field Values

## 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:
  - `CronExpression.parse(String)`

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:
  - `CronTrigger(String, java.util.TimeZone)`
  - `TimeZone`

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:
  - `fixedRate()`

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:
  - `fixedDelay()`

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:
  - `initialDelay()`

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:
  - `SchedulingAwareRunnable.getQualifier()`

Default:
  ""