Annotation Interface HandleSchedule

@Documented @Retention(RUNTIME) @Target({METHOD,CONSTRUCTOR}) @HandleMessage(SCHEDULE) public @interface HandleSchedule
Marks a method or constructor as a handler for scheduled messages (MessageType.SCHEDULE).

These handlers are invoked in response to scheduled triggers, typically time-based.

Scheduled messages may originate from an explicit schedule call (see MessageScheduler), or from a payload annotated with Periodic, which enables automatic rescheduling after each invocation.

Schedule handlers can also run locally. Mark a handler with LocalHandler, or place the @HandleSchedule method on the scheduled payload type itself without @TrackSelf. Local schedule handlers are triggered by Fluxzero's task scheduler and can be used for in-process recurring work.

Return behavior

A @HandleSchedule method may return a value to control rescheduling behavior:
  • null: continue scheduling using the default strategy if the schedule is Periodic.
  • 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.

To cancel a periodic schedule, throw a CancelPeriodic exception.

Example: Dynamic continuation using payload return

@HandleSchedule
PollUpdates on(PollUpdates poll) {
    var updates = Fluxzero.queryAndWait(poll);
    // Process updates
    return new PollUpdates(updates.getContinuationToken());
}
If PollUpdates is annotated with Periodic, its delay or cron expression will be used for rescheduling.

Example: Return a delay for the next schedule

@HandleSchedule
Duration on(HealthCheck ping) {
    if (!isAlive()) {
        throw new CancelPeriodic("Service offline");
    }
    return Duration.ofSeconds(30);
}
This will schedule the same ping message to be retried after 30 seconds.
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<?>[]
    allowedClasses
    Restricts which payload types this handler may be invoked for.
    boolean
    disabled
    If true, disables this handler during discovery.
    MissingProtectedDataPolicy
    onMissingProtectedData
    Determines how the handler responds when referenced protected data is no longer available.

  • Element Details

    • onMissingProtectedData

      MissingProtectedDataPolicy onMissingProtectedData
      Determines how the handler responds when referenced protected data is no longer available.
      Default:
      DEFAULT

    • disabled

      boolean disabled
      If true, disables this handler during discovery.
      Default:
      false

    • allowedClasses

      Class<?>[] allowedClasses
      Restricts which payload types this handler may be invoked for.
      Default:
      {}