Interface MessageScheduler

All Superinterfaces:
Namespaced<MessageScheduler>
All Known Implementing Classes:
DefaultMessageScheduler
public interface MessageScheduler extends Namespaced<MessageScheduler>
Interface for scheduling deferred or periodic execution of messages in the Fluxzero Runtime.

The MessageScheduler provides functionality for:

  • Deferring arbitrary payloads (to be handled via HandleSchedule).
  • Scheduling commands (to be handled via standard @HandleCommand handlers).
  • Recurring execution using cron expressions via the Periodic annotation.

Scheduling semantics

When using schedule(...):

  • Scheduled payloads are delivered to handler methods annotated with @HandleSchedule.
  • Used when the intention is to invoke scheduling-specific logic or workflows.

When using scheduleCommand(...):

  • The scheduled payload will be dispatched as a command at the configured deadline.
  • Handlers annotated with @HandleCommand will receive the message, just like normal commands.
  • This is useful for scenarios where both immediate and delayed invocation use the same handler logic.

Schedule identity

All schedules are identified by a scheduleId. It is recommended to always pass a scheduleId. However, if one is not given, it is obtained from the toString() value of the Schedule payload. If a schedule with the same ID already exists:

  • It is replaced by default.
  • Use ifAbsent = true to ensure the schedule is only created if it does not already exist.

Typical usage

This interface underpins the static helpers in Fluxzero, such as: 
    Fluxzero.schedule(myPayload, Duration.ofMinutes(5));
    Fluxzero.scheduleCommand(myCommand, Instant.now().plusSeconds(10));
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelSchedule(@NonNull Object scheduleId)
    Cancel a previously scheduled message or command by ID.
    Optional<Schedule>
    getSchedule(@NonNull Object scheduleId)
    Look up an existing schedule.
    default void
    schedule(@NonNull Schedule message)
    Schedule a message object (typically of type Schedule) for execution, using the Guarantee.SENT guarantee.
    default void
    schedule(@NonNull Schedule message, boolean ifAbsent)
    Schedule a message, optionally skipping if already present, using the Guarantee.SENT guarantee.
    CompletableFuture<Void>
    schedule(Schedule message, boolean ifAbsent, io.fluxzero.common.Guarantee guarantee)
    Schedule the given Schedule object, optionally skipping if already present, using the specified guarantee.
    default void
    schedule(@NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Duration delay)
    Schedule a message with payload and metadata using a delay, using the Guarantee.SENT guarantee.
    default void
    schedule(@NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Instant deadline)
    Schedule a message with payload and metadata, using the Guarantee.SENT guarantee.
    default void
    schedule(@NonNull Object schedule, Object scheduleId, Duration delay)
    Schedule a message with a custom ID using a delay.
    default void
    schedule(@NonNull Object schedule, Object scheduleId, Instant deadline)
    Schedule a message with the given ID and deadline, using the Guarantee.SENT guarantee.
    default String
    schedule(@NonNull Object schedule, Duration delay)
    Schedule a message using a delay from the current time, using the Guarantee.SENT guarantee.
    default String
    schedule(@NonNull Object schedule, Instant deadline)
    Schedule a message to be triggered at the given deadline, using the Guarantee.SENT guarantee.
    default void
    scheduleCommand(@NonNull Schedule message)
    Schedule a command message using the given scheduling settings, using the Guarantee.SENT guarantee.
    default void
    scheduleCommand(@NonNull Schedule message, boolean ifAbsent)
    Schedule a command using the given scheduling settings if no other with same ID exists, using the Guarantee.SENT guarantee.
    CompletableFuture<Void>
    scheduleCommand(Schedule message, boolean ifAbsent, io.fluxzero.common.Guarantee guarantee)
    Schedule a command using the given scheduling settings, using the provided Guarantee.
    default void
    scheduleCommand(@NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Duration delay)
    Schedule a command with metadata and delay, using the Guarantee.SENT guarantee.
    default void
    scheduleCommand(@NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Instant deadline)
    Schedule a command message with attached metadata, using the Guarantee.SENT guarantee.
    default void
    scheduleCommand(@NonNull Object schedule, Object scheduleId, Duration delay)
    Schedule a command with the given ID and delay, using the Guarantee.SENT guarantee.
    default void
    scheduleCommand(@NonNull Object schedule, Object scheduleId, Instant deadline)
    Schedule a command using a specific deadline, using the Guarantee.SENT guarantee.
    default String
    scheduleCommand(@NonNull Object schedule, Duration delay)
    Schedule a command to execute after given delay, using the Guarantee.SENT guarantee.
    default String
    scheduleCommand(@NonNull Object schedule, Instant deadline)
    Schedule a command message for future execution.
    default String
    schedulePeriodic(@NonNull Object value, Object scheduleId)
    Schedule a periodic message using the given ID and the @Periodic annotation, using the Guarantee.SENT guarantee.
    default String
    schedulePeriodic(Object value)
    Schedule a periodic message using the @Periodic annotation on its class, using the Guarantee.SENT guarantee.

    Methods inherited from interface Namespaced

    forDefaultNamespace, forNamespace

  • Method Details

    • schedulePeriodic

      default String schedulePeriodic(Object value)
      Schedule a periodic message using the @Periodic annotation on its class, using the Guarantee.SENT guarantee.
      Parameters:
      value - the payload to schedule periodically
      Returns:
      the schedule ID
      Throws:
      IllegalArgumentException - if the annotation is missing or misconfigured

    • schedulePeriodic

      default String schedulePeriodic(@NonNull @NonNull Object value, Object scheduleId)
      Schedule a periodic message using the given ID and the @Periodic annotation, using the Guarantee.SENT guarantee.
      Parameters:
      value - the payload to schedule periodically
      scheduleId - a custom ID or null to use value#toString
      Returns:
      the effective schedule ID

    • schedule

      default String schedule(@NonNull @NonNull Object schedule, Instant deadline)
      Schedule a message to be triggered at the given deadline, using the Guarantee.SENT guarantee.

      The schedule ID will be determined by calling schedule#toString.

      Parameters:
      schedule - the message to schedule
      deadline - the absolute time to trigger the message
      Returns:
      the schedule ID

    • schedule

      default String schedule(@NonNull @NonNull Object schedule, Duration delay)
      Schedule a message using a delay from the current time, using the Guarantee.SENT guarantee.

      The schedule ID will be determined by calling schedule#toString.

      Parameters:
      schedule - the message to schedule
      delay - delay duration until the schedule triggers
      Returns:
      the schedule ID

    • schedule

      default void schedule(@NonNull @NonNull Object schedule, Object scheduleId, Duration delay)
      Schedule a message with a custom ID using a delay.
      Parameters:
      schedule - the message to schedule
      scheduleId - the unique ID of the schedule
      delay - the delay until triggering

    • schedule

      default void schedule(@NonNull @NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Instant deadline)
      Schedule a message with payload and metadata, using the Guarantee.SENT guarantee.
      Parameters:
      schedulePayload - the message payload
      metadata - metadata to attach
      scheduleId - the unique schedule ID
      deadline - the deadline for triggering the schedule

    • schedule

      default void schedule(@NonNull @NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Duration delay)
      Schedule a message with payload and metadata using a delay, using the Guarantee.SENT guarantee.
      Parameters:
      schedulePayload - the message payload
      metadata - metadata to attach
      scheduleId - the schedule ID
      delay - delay from now until triggering

    • schedule

      default void schedule(@NonNull @NonNull Object schedule, Object scheduleId, Instant deadline)
      Schedule a message with the given ID and deadline, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the object to schedule
      scheduleId - unique schedule ID
      deadline - the absolute time at which the schedule should trigger

    • schedule

      default void schedule(@NonNull @NonNull Schedule message)
      Schedule a message object (typically of type Schedule) for execution, using the Guarantee.SENT guarantee.
      Parameters:
      message - the message to schedule

    • schedule

      default void schedule(@NonNull @NonNull Schedule message, boolean ifAbsent)
      Schedule a message, optionally skipping if already present, using the Guarantee.SENT guarantee.
      Parameters:
      message - the schedule message
      ifAbsent - whether to skip scheduling if an existing schedule is present

    • schedule

      CompletableFuture<Void> schedule(Schedule message, boolean ifAbsent, io.fluxzero.common.Guarantee guarantee)
      Schedule the given Schedule object, optionally skipping if already present, using the specified guarantee.
      Parameters:
      message - the schedule message
      ifAbsent - only schedule if not already scheduled
      guarantee - the delivery guarantee to use
      Returns:
      a CompletableFuture completing when the message is successfully scheduled

    • scheduleCommand

      default String scheduleCommand(@NonNull @NonNull Object schedule, Instant deadline)
      Schedule a command message for future execution. This is similar to schedule(Object, Instant) but ensures the message is dispatched as a command, using the Guarantee.SENT guarantee.

      The schedule ID will be determined by calling schedule#toString.

      Parameters:
      schedule - the command to schedule
      deadline - the deadline for execution
      Returns:
      the schedule ID

    • scheduleCommand

      default String scheduleCommand(@NonNull @NonNull Object schedule, Duration delay)
      Schedule a command to execute after given delay, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the command to schedule
      delay - delay until execution
      Returns:
      the schedule ID

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Object schedule, Object scheduleId, Duration delay)
      Schedule a command with the given ID and delay, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the command to schedule
      scheduleId - schedule ID
      delay - delay until execution

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Instant deadline)
      Schedule a command message with attached metadata, using the Guarantee.SENT guarantee.
      Parameters:
      schedulePayload - payload of the command
      metadata - metadata to attach
      scheduleId - schedule ID
      deadline - execution deadline

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Object schedulePayload, io.fluxzero.common.api.Metadata metadata, Object scheduleId, Duration delay)
      Schedule a command with metadata and delay, using the Guarantee.SENT guarantee.
      Parameters:
      schedulePayload - payload to schedule
      metadata - metadata to attach
      scheduleId - schedule ID
      delay - delay duration

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Object schedule, Object scheduleId, Instant deadline)
      Schedule a command using a specific deadline, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the command object or message
      scheduleId - the schedule ID
      deadline - deadline for triggering the schedule

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Schedule message)
      Schedule a command message using the given scheduling settings, using the Guarantee.SENT guarantee.
      Parameters:
      message - the command message

    • scheduleCommand

      default void scheduleCommand(@NonNull @NonNull Schedule message, boolean ifAbsent)
      Schedule a command using the given scheduling settings if no other with same ID exists, using the Guarantee.SENT guarantee.
      Parameters:
      message - the command schedule
      ifAbsent - whether to skip if already scheduled

    • scheduleCommand

      CompletableFuture<Void> scheduleCommand(Schedule message, boolean ifAbsent, io.fluxzero.common.Guarantee guarantee)
      Schedule a command using the given scheduling settings, using the provided Guarantee.
      Parameters:
      message - the command schedule
      ifAbsent - skip if existing schedule is present
      guarantee - the delivery guarantee to apply
      Returns:
      a future indicating when the command is scheduled

    • cancelSchedule

      void cancelSchedule(@NonNull @NonNull Object scheduleId)
      Cancel a previously scheduled message or command by ID.
      Parameters:
      scheduleId - the ID of the schedule to cancel

    • getSchedule

      Optional<Schedule> getSchedule(@NonNull @NonNull Object scheduleId)
      Look up an existing schedule.
      Parameters:
      scheduleId - the ID of the schedule
      Returns:
      the schedule if found