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.

Auto-started cron schedules store an internal metadata entry with the cron schema that created them. On startup, Fluxzero replaces such a stored schedule when the cron schema has changed. Schedules that were delayed explicitly by returning Duration, Instant, or Schedule from a handler are not marked as cron-created and are left untouched by automatic start.

When the matching HandleSchedule method is local (for example through LocalHandler, or because it is declared on a non-@TrackSelf payload type), periodic execution is triggered through Fluxzero's task scheduler.

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:

  • 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:

    • USE_DEFAULT_INITIAL_DELAY_PROPERTY

      static final String USE_DEFAULT_INITIAL_DELAY_PROPERTY
      Feature flag that enables the new implicit initial-delay behavior without changing ApplicationProperties.DEFAULTS_VERSION_PROPERTY. When set to true, initialDelay() values below 0 mean that no explicit initial delay was configured.
      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. Relevant when autoStart() is true or when a schedule is started via MessageScheduler.schedulePeriodic(Object). A value of 0 schedules the first invocation immediately. Positive values delay the first invocation by the configured amount.

      The default -1 means that no explicit initial delay was configured. With compatibility defaults, Fluxzero treats this implicit value as 0 to preserve the previous immediate autostart behavior. With the new defaults behavior, enabled via USE_DEFAULT_INITIAL_DELAY_PROPERTY or ApplicationProperties.DEFAULTS_VERSION_PROPERTY, fixed-delay schedules start after delay() and cron schedules start at the next cron fire time.

      Default:
      -1L