Migrating from JVM job scheduling

Background work on the JVM usually arrives as one of three things: Spring's @Async and @Scheduled, a Quartz scheduler, or a JMS/AMQP listener in front of a broker. FlexiQ replaces all three with one client and one store.

The three shifts worth understanding before you start:

• Durability comes from the store, not the broker. @Async work lives in an in-process executor and is gone on restart; FlexiQ jobs are durable records in the configured store and survive it. There is no broker, exchange or DLX to declare.
• Tasks are named descriptors. A producer holds a Task<T> — a name plus a payload type — and never needs the handler. That is what lets the web tier enqueue without the dependencies that do the work.
• Scheduling is not a separate service. Cron and delayed jobs fire from the same running worker that executes tasks, so there is no Quartz scheduler to cluster or a QuartzJobStore to configure.

Concept map

Side by side

// Spring @Async — in-process, lost on restart, no retry
@Async
public void sendWelcome(long userId) { mailer.send(userId); }

// FlexiQ — a durable job with a retry budget and a timeout
Task<Long> SEND_WELCOME = Task.of("send_welcome", Long.class)
        .queue("emails")
        .maxRetries(3)
        .timeout(Duration.ofSeconds(30));

flexiq.enqueue(SEND_WELCOME, userId);            // producer, returns a job id

flexiq.worker()                                   // consumer, its own process
        .queues("emails")
        .handle(SEND_WELCOME, mailer::send)
        .start();

What changes

• One store, chosen by how many machines you have. SQLite for a single host, Postgres when producers and workers are on different ones. See backends.
• The producer stops needing the handler. Split the descriptors into a class the web tier can depend on; keep .handle(...) with the worker.
• Retries are declared, not coded. A redelivery policy on a listener becomes maxRetries plus a RetryPolicy on the descriptor, enforced by the Rust scheduler — so a worker that dies mid-backoff does not lose the schedule. See retries.
• Exhausted jobs land somewhere you can see. No DLX to bind: the dead-letter store keeps the payload and the per-attempt error history — dead-letter queue.
• Cron needs a running worker. registerPeriodic fires from the worker poll loop. If no worker is running, nothing fires — there is no independent scheduler process, which is the point, but it is a different failure mode from Quartz. See scheduling.