Package io.fluxcapacitor.javaclient.scheduling

Interface MessageScheduler

All Known Implementing Classes:
DefaultMessageScheduler
public interface MessageScheduler
Interface for scheduling deferred or periodic execution of messages in the Flux Capacitor platform.

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. By default, one is generated unless explicitly passed. 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 FluxCapacitor, such as: 
     FluxCapacitor.schedule(myPayload, Duration.ofMinutes(5));
     FluxCapacitor.scheduleCommand(myCommand, Instant.now().plusSeconds(10));
See Also:

  • 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(Object value, String 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 generate one
      Returns:
      the effective schedule ID

    • schedule

      default String schedule(Object schedule, Instant deadline)
      Schedule a message to be triggered at the given deadline, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the message to schedule
      deadline - the absolute time to trigger the message
      Returns:
      the generated schedule ID

    • schedule

      default String schedule(Object schedule, Duration delay)
      Schedule a message using a delay from the current time, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the message to schedule
      delay - delay duration until the schedule triggers
      Returns:
      the generated schedule ID

    • schedule

      default void schedule(Object schedule, String 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(Object schedulePayload, Metadata metadata, String 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(Object schedulePayload, Metadata metadata, String 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(Object schedule, String 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(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(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, 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(Object schedule, Instant deadline)
      Schedule a command message for future execution. This is similar to schedule(java.lang.Object, java.time.Instant) but ensures the message is dispatched as a command, using the Guarantee.SENT guarantee.
      Parameters:
      schedule - the command to schedule
      deadline - the deadline for execution
      Returns:
      the generated schedule ID

    • scheduleCommand

      default String scheduleCommand(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(Object schedule, String 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(Object schedulePayload, Metadata metadata, String 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(Object schedulePayload, Metadata metadata, String 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(Object schedule, String 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(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(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, 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(String scheduleId)
      Cancel a previously scheduled message or command by ID.
      Parameters:
      scheduleId - the ID of the schedule to cancel

    • getSchedule

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