Annotation Interface Periodic
Schedule
) or its handler method as part of a periodic schedule.
Periodic schedules are automatically rescheduled after each invocation using either a fixed delay or a cron expression. This enables use cases like polling APIs, triggering maintenance routines, or recurring status checks.
This annotation can be placed on either:
- The payload class of a
Schedule
, marking it as inherently periodic - A handler method annotated with
HandleSchedule
, overriding periodic behavior
Rescheduling Behavior
- If
cron()
is specified, it defines when the schedule should run (overridesdelay()
) - If
delay()
is used andcron
is blank, the schedule runs with fixed delays - The
initialDelay()
(if ≥ 0) applies once when the schedule is first started (only ifautoStart()
istrue
)
Automatic Start
By default, the schedule is automatically started when the message is handled or the system starts. SetautoStart()
to false
to disable this behavior.
Error Handling
If the schedule handler throws an exception:- If
continueOnError()
istrue
(default), the schedule continues - If
delayAfterError()
is set (≥ 0), it overrides the normal delay after an error - If
continueOnError
isfalse
, the schedule is stopped after an error
Stopping a Periodic Schedule
To stop a periodic schedule explicitly from a handler, throwCancelPeriodic
.
Returning null
from the handler method does not stop the schedule — it simply continues with the default rescheduling.
Interaction with HandleSchedule
When used with a @HandleSchedule
method, the return value influences scheduling:
null
orvoid
: continue scheduling using thePeriodic
settings.Duration
orInstant
: overrides the next schedule delay or time.- A new payload: schedules the returned object as the next scheduled message. If this new payload is annotated
with
Periodic
, the periodic settings on that payload take precedence. - Returning a new
Schedule
reschedules that message using the specified payload and deadline.
Example: Schedule Every 5 Minutes
@Value
@Periodic(delay = 5, timeUnit = TimeUnit.MINUTES)
public class RefreshData { ... }
Example: Weekly Schedule via Cron
@Periodic(cron = "0 0 * * MON", timeZone = "Europe/Amsterdam")
@HandleSchedule
void weeklySync(Schedule schedule) {
...
}
- See Also:
-
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionboolean
Returns true if this periodic schedule should be automatically started if it's not already active.boolean
Returns true if the schedule should continue after an error.Define a unix-like cron expression.long
Returns the schedule delay intimeUnit()
units.long
Returns the schedule delay intimeUnit()
units after handling of the last schedule gave rise to an exception.long
Returns the initial schedule delay.Returns the id of the periodic schedule.Returns the unit fordelay()
andinitialDelay()
.A time zone id for which the cron expression will be resolved. -
Field Summary
Fields
-
Field Details
-
DISABLED
Special expression that can be used to disable automatic periodic scheduling if passed tocron()
. If the schedule was already running and is disabled later on using this expression, any previously scheduled messages will be ignored.- See Also:
-
-
Element Details
-
cron
String cronDefine a unix-like cron expression. If a cron value is specified thedelay()
in milliseconds is ignored.The fields read from left to right are interpreted as follows.
- minute
- hour
- day of month
- month
- day of week
For example,
"0 * * * MON-FRI"
means at the start of every hour on weekdays.It is possible to refer to an application property, e.g. by specifying `${someFetchSchedule}` as cron value. To disable the schedule altogether if the property is *not* set, specify `${someFetchSchedule:-}`.
- See Also:
- Default:
""
-
timeZone
String timeZoneA time zone id for which the cron expression will be resolved. Defaults to UTC.- Default:
"UTC"
-
scheduleId
String scheduleIdReturns the id of the periodic schedule. Defaults to the fully qualified name of the schedule class.- Default:
""
-
autoStart
boolean autoStartReturns true if this periodic schedule should be automatically started if it's not already active. Defaults totrue
.- Default:
true
-
delay
long delayReturns the schedule delay intimeUnit()
units. Only used ifcron()
is blank, in which case this value should be a positive number.- Default:
-1L
-
continueOnError
boolean continueOnErrorReturns true if the schedule should continue after an error. Defaults totrue
.- Default:
true
-
delayAfterError
long delayAfterErrorReturns the schedule delay intimeUnit()
units after handling of the last schedule gave rise to an exception.If this value is smaller than 0 (the default) this setting is ignored and the schedule will continue as if the exception hadn't been triggered. If
continueOnError()
is false, this setting is ignored as well.- Default:
-1L
-
timeUnit
TimeUnit timeUnit- Default:
MILLISECONDS
-
initialDelay
long initialDelayReturns the initial schedule delay. Only relevant whenautoStart()
is true. If initialDelay is negative, the initial schedule will fire after the default delay (configured either viacron()
ordelay()
).- Default:
0L
-