Message scheduling

Fluxzero allows scheduling messages for future delivery using the MessageScheduler.

Here’s an example that schedules work 30 days after an account closes and cancels it if the account reopens:

Java

class UserLifecycleHandler {
    @HandleEvent
    void handle(AccountClosed event) {
        Fluxzero.schedule(
                new TerminateAccount(event.getUserId()),
                "AccountClosed-" + event.getUserId(),
                Duration.ofDays(30)
        );
    }

    @HandleEvent
    void handle(AccountReopened event) {
        Fluxzero.cancelSchedule("AccountClosed-" + event.getUserId());
    }

    @HandleSchedule
    void handle(TerminateAccount schedule) {
        // Recheck that the account is still closed, then perform termination
    }
}

Kotlin

class UserLifecycleHandler {

    @HandleEvent
    fun handle(event: AccountClosed) {
        Fluxzero.schedule(
            TerminateAccount(event.userId),
            "AccountClosed-${event.userId}",
            Duration.ofDays(30)
        )
    }

    @HandleEvent
    fun handle(event: AccountReopened) {
        Fluxzero.cancelSchedule("AccountClosed-${event.userId}")
    }

    @HandleSchedule
    fun handle(schedule: TerminateAccount) {
        // Recheck that the account is still closed, then perform termination
    }
}

Note

Before performing the delayed action, check that it is still needed. For replay-safe creation and cancellation, see Schedule identity and lifecycle below.

---

Scheduling commands

You can also schedule commands directly using scheduleCommand(...).

Java

class UserLifecycleHandler {
    @HandleEvent
    void handle(AccountClosed event) {
        Fluxzero.scheduleCommand(
                new TerminateAccount(event.getUserId()),
                "AccountClosed-" + event.getUserId(),
                Duration.ofDays(30));
    }

    @HandleEvent
    void handle(AccountReopened event) {
        Fluxzero.cancelSchedule("AccountClosed-" + event.getUserId());
    }
}

Kotlin

class UserLifecycleHandler {

    @HandleEvent
    fun handle(event: AccountClosed) {
        Fluxzero.scheduleCommand(
            TerminateAccount(event.userId),
            "AccountClosed-${event.userId}",
            Duration.ofDays(30)
        )
    }

    @HandleEvent
    fun handle(event: AccountReopened) {
        Fluxzero.cancelSchedule("AccountClosed-${event.userId}")
    }
}

---

Schedule identity and lifecycle

Use ScheduleId when different schedule categories can share the same domain ID. Fluxzero uses its stable type:id representation for scheduling, lookup and cancellation.

Java

ScheduleId expiryId = ScheduleId.of("account-expiry", userId);
Fluxzero.schedule(new TerminateAccount(userId), expiryId, Duration.ofDays(30));
Fluxzero.cancelSchedule(expiryId);

Kotlin

val expiryId = ScheduleId.of("account-expiry", userId)
Fluxzero.schedule(TerminateAccount(userId), expiryId, Duration.ofDays(30))
Fluxzero.cancelSchedule(expiryId)

Work tied to a Model

Declare @Parent on a scheduled payload to cancel pending work when its committed Model owner is deleted. See Parent-owned schedules.

Check that delayed work still belongs

Cancellation cannot recall work that has already been delivered. Check current state before performing a delayed action. If an event handler manages schedules, replaying an old event should not restore obsolete work; see current-state schedule reconciliation for that pattern.

Periodic scheduling

Fluxzero supports recurring message schedules via the @Periodic annotation. This makes it easy to run background tasks on a fixed interval or cron schedule.

You can apply @Periodic to a schedule payload or a @HandleSchedule method.

Java

@Periodic(delay = 5, timeUnit = TimeUnit.MINUTES)
public record RefreshData(String index) {
}

@Periodic(cron = "0 0 * * MON", timeZone = "Europe/Amsterdam")
@HandleSchedule
void weeklySync(PollData schedule) {
    ...
}

Kotlin

@Periodic(delay = 5, timeUnit = TimeUnit.MINUTES)
data class RefreshData(val index: String)

@Periodic(cron = "0 0 * * MON", timeZone = "Europe/Amsterdam")
@HandleSchedule
fun weeklySync(schedule: PollData) {
    ...
}

Tip

Cron expressions use UTC by default. Use the timeZone parameter to run tasks in your local time zone.

Initial autostart timing

initialDelay defaults to -1, which means no explicit initial delay was configured. Compatibility defaults treat that implicit value as 0, so an auto-started periodic schedule starts immediately. New defaults can be selected with:

fluxzero.defaults.version=2026.05.21
# equivalent explicit setting:
fluxzero.scheduling.periodic.useDefaultInitialDelay=true

With this behavior, fixed-delay schedules first run after delay, and cron schedules first run at the next cron match. For example, @Periodic(delay = 60_000) first runs after 60 seconds, while @Periodic(cron = "*/5 * * * *") first runs at the next five-minute boundary. Set initialDelay = 0 when the first run should be immediate.

---

Behavior and advanced options

• @Periodic only applies to scheduled messages (used with @HandleSchedule)
• The schedule automatically reschedules itself after every execution unless cancelled
• You can:
  • Return void or null to use the same delay next time
  • Return a Duration or Instant to customize the next deadline
  • Return a new Schedule payload to completely redefine the next cycle
• On error:
  • The default is to continue (continueOnError = true)
  • Use delayAfterError to delay retries after failure
  • Throw CancelPeriodic to stop the schedule completely
• Use @Periodic(autoStart = false) to prevent the schedule from activating on startup
• The schedule ID defaults to the payload class name but can be customized using scheduleId

---

Example: polling with error fallback

Java

@Periodic(delay = 60, timeUnit = TimeUnit.MINUTES, delayAfterError = 10)
@HandleSchedule
void pollExternalService(PollTask pollTask) {
    try {
        externalService.fetchData();
    } catch (Exception e) {
        log.warn("Polling failed, will retry in 10 minutes", e);
        throw e;
    }
}

Kotlin

@Periodic(delay = 60, timeUnit = TimeUnit.MINUTES, delayAfterError = 10)
@HandleSchedule
fun pollExternalService(task: PollTask) {
    try {
        externalService.fetchData()
    } catch (e: Exception) {
        log.warn("Polling failed, will retry in 10 minutes", e)
        throw e
    }
}

In this example:

• The task runs every hour
• If it fails, it retries after 10 minutes
• If it succeeds, it returns to the hourly schedule

Tip

Schedules are fully auditable, correlated to the original event, and can be canceled or monitored like any other message. You can use them for cleanup, retries, reminders, or long-lived workflows.

Delivery and completion

SDK 2.x scheduling and cancellation convenience methods return without waiting for a remote acknowledgement. When you need confirmation that a schedule was stored, use the future-returning overload, for example messageScheduler.schedule(schedule, false, Guarantee.STORED), and await its future. This confirms storage, not execution of the delayed action.

See Sending messages for shared delivery settings and MessageScheduler for the exact overloads and completion contracts.