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:
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    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 in timeUnit() units.
    long
    Returns the schedule delay in timeUnit() 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 for delay() and initialDelay().
    A time zone id for which the cron expression will be resolved.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Special expression that can be used to disable automatic periodic scheduling if passed to cron().
  • 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:
  • 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:
      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