Annotation Interface Periodic

@Documented
@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
public @interface Periodic

Declares a message (typically a 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 (overrides delay())
• If delay() is used and cron is blank, the schedule runs with fixed delays
• The initialDelay() (if ≥ 0) applies once when the schedule is first started (only if autoStart() is true)

Automatic Start

By default, the schedule is automatically started when the message is handled or the system starts. Set autoStart() to false to disable this behavior.

Error Handling

If the schedule handler throws an exception:

• If continueOnError() is true (default), the schedule continues
• If delayAfterError() is set (≥ 0), it overrides the normal delay after an error
• If continueOnError is false, the schedule is stopped after an error

Stopping a Periodic Schedule

To stop a periodic schedule explicitly from a handler, throw CancelPeriodic. 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 or void: continue scheduling using the Periodic settings.
• Duration or Instant: 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:

• HandleSchedule
• Schedule
• CancelPeriodic

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DISABLED	Special expression that can be used to disable automatic periodic scheduling if passed to cron().

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	autoStart	Returns true if this periodic schedule should be automatically started if it's not already active.
boolean	continueOnError	Returns true if the schedule should continue after an error.
String	cron	Define a unix-like cron expression.
long	delay	Returns the schedule delay in timeUnit() units.
long	delayAfterError	Returns the schedule delay in timeUnit() units after handling of the last schedule gave rise to an exception.
long	initialDelay	Returns the initial schedule delay.
String	scheduleId	Returns the id of the periodic schedule.
TimeUnit	timeUnit	Returns the unit for delay() and initialDelay().
String	timeZone	A time zone id for which the cron expression will be resolved.

Field Details

DISABLED

static final String DISABLED

Special expression that can be used to disable automatic periodic scheduling if passed to cron(). If the schedule was already running and is disabled later on using this expression, any previously scheduled messages will be ignored.

See Also:

• Constant Field Values

Element Details

cron

String cron

Define a unix-like cron expression. If a cron value is specified the delay() 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:

• for more info on how the string is parsed.

Default:

""

timeZone

String timeZone

A time zone id for which the cron expression will be resolved. Defaults to UTC.

Default:

"UTC"

scheduleId

String scheduleId

Returns the id of the periodic schedule. Defaults to the fully qualified name of the schedule class.

Default:

""

autoStart

boolean autoStart

Returns true if this periodic schedule should be automatically started if it's not already active. Defaults to true.

Default:

true

delay

long delay

Returns the schedule delay in timeUnit() units. Only used if cron() is blank, in which case this value should be a positive number.

Default:

-1L

continueOnError

boolean continueOnError

Returns true if the schedule should continue after an error. Defaults to true.

Default:

true

delayAfterError

long delayAfterError

Returns the schedule delay in timeUnit() 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

Returns the unit for delay() and initialDelay(). Defaults to TimeUnit.MILLISECONDS.

Default:

MILLISECONDS

initialDelay

long initialDelay

Returns the initial schedule delay. Only relevant when autoStart() is true. If initialDelay is negative, the initial schedule will fire after the default delay (configured either via cron() or delay()).

Default:

0L