Spring Context 6.1.4 · org.springframework.scheduling.annotation.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.

Field Summary

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

Method Summary

Modifier and Type	Method and Description
public String	Returns: an expression that can be parsed to a cron schedule 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.
public long	Returns: the delay fixedDelay() Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.
public String	Returns: the delay as a String value — for example, a placeholder or a `java.time.Duration` compliant value fixedDelayString() Execute the annotated method with a fixed period between the end of the last invocation and the start of the next.
public long	Returns: the period fixedRate() Execute the annotated method with a fixed period between invocations.
public String	Returns: the period as a String value — for example, a placeholder or a `java.time.Duration` compliant value fixedRateString() Execute the annotated method with a fixed period between invocations.
public long	Returns: the initial initialDelay() Number of units of time to delay before the first execution of a `fixedRate` or `fixedDelay` task.
public String	Returns: the initial delay as a String value — for example, a placeholder or a `java.time.Duration` compliant value initialDelayString() Number of units of time to delay before the first execution of a `fixedRate` or `fixedDelay` task.
public String	scheduler() A qualifier for determining a scheduler to run this scheduled method on.
public TimeUnit	Returns: the `TimeUnit` to use timeUnit() The `TimeUnit` to use for `fixedDelay`, `fixedDelayString`, `fixedRate`, `fixedRateString`, `initialDelay`, and `initialDelayString`.
public String	Returns: a zone id accepted by `java.util.TimeZone#getTimeZone(String)`, or an empty String to indicate the scheduler's default time zone zone() A time zone for which the cron expression will be resolved.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Field Detail

CRON_DISABLED back to summary

CRON_DISABLED	back to summary
public 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`

public 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

Method Detail

cron back to summary

cron	back to summary
public String cron() A cron-like expression, extending the usual UNX 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:String an expression that can be parsed to a cron schedule See Also `org.springframework.scheduling.support.CronExpression#parse(String)`

public 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:String: an expression that can be parsed to a cron schedule
See Also: org.springframework.scheduling.support.CronExpression#parse(String)

fixedDelay back to summary

fixedDelay	back to summary
public 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 `org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler`. Returns:long the delay

public 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 org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler.

Returns:long: the delay

fixedDelayString back to summary

fixedDelayString	back to summary
public String fixedDelayString() 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`. This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions. NOTE: With virtual threads, fixed rates and cron triggers are recommended over fixed delays. Fixed-delay tasks operate on a single scheduler thread with `org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler`. Returns:String the delay as a String value — for example, a placeholder or a `java.time.Duration` compliant value Since 3.2.2 See Also `fixedDelay()`

public String fixedDelayString()

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.

This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions.

Returns:String: the delay as a String value — for example, a placeholder or a java.time.Duration compliant value
Since: 3.2.2
See Also: fixedDelay()

fixedRate back to summary

fixedRate	back to summary
public 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:long the period

public 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:long: the period

fixedRateString back to summary

fixedRateString	back to summary
public String fixedRateString() Execute the annotated method with a fixed period between invocations. The time unit is milliseconds by default but can be overridden via `timeUnit`. This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions. Returns:String the period as a String value — for example, a placeholder or a `java.time.Duration` compliant value Since 3.2.2 See Also `fixedRate()`

public String fixedRateString()

Execute the annotated method with a fixed period between invocations.

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

This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions.

Returns:String: the period as a String value — for example, a placeholder or a java.time.Duration compliant value
Since: 3.2.2
See Also: fixedRate()

initialDelay back to summary

initialDelay	back to summary
public 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:long the initial Since 3.2

public 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:long: the initial
Since: 3.2

initialDelayString back to summary

initialDelayString	back to summary
public String initialDelayString() 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`. This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions. Returns:String the initial delay as a String value — for example, a placeholder or a `java.time.Duration` compliant value Since 3.2.2 See Also `initialDelay()`

public String initialDelayString()

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.

This attribute variant supports Spring-style "${...}" placeholders as well as SpEL expressions.

Returns:String: the initial delay as a String value — for example, a placeholder or a java.time.Duration compliant value
Since: 3.2.2
See Also: initialDelay()

scheduler back to summary

scheduler	back to summary
public 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 `org.springframework.scheduling.TaskScheduler` or `java.util.concurrent.ScheduledExecutorService` bean definition. Since 6.1 See Also `org.springframework.scheduling.SchedulingAwareRunnable#getQualifier()`

public 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 org.springframework.scheduling.TaskScheduler or java.util.concurrent.ScheduledExecutorService bean definition.

Since: 6.1
See Also: org.springframework.scheduling.SchedulingAwareRunnable#getQualifier()

timeUnit back to summary

timeUnit	back to summary
public 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 `java.time.Duration` values supplied via `fixedDelayString`, `fixedRateString`, or `initialDelayString`. Returns:TimeUnit the `TimeUnit` to use Since 5.3.10

public 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 java.time.Duration values supplied via fixedDelayString, fixedRateString, or initialDelayString.

Returns:TimeUnit: the TimeUnit to use
Since: 5.3.10

zone back to summary

zone	back to summary
public 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:String a zone id accepted by `java.util.TimeZone#getTimeZone(String)`, or an empty String to indicate the scheduler's default time zone Since 4.0 See Also `org.springframework.scheduling.support.CronTrigger#CronTrigger(String, java.util.TimeZone)`, `java.util.TimeZone`

public 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:String: a zone id accepted by java.util.TimeZone#getTimeZone(String), or an empty String to indicate the scheduler's default time zone
Since: 4.0
See Also: org.springframework.scheduling.support.CronTrigger#CronTrigger(String, java.util.TimeZone), java.util.TimeZone

public @Interface Scheduled

Field Summary

Method Summary

Field Detail

Method Detail