Skip to main content

Job context

Every handler receives a JobContext. The worker builds it; you never construct one. It exposes the job's metadata, a way to report progress, the cancellation handle, and a logger pre-bound to this job.

public void execute(NewUserEvent payload, JobContext ctx) {
    ctx.logger().log(System.Logger.Level.INFO,
        "handling " + ctx.jobId() + " attempt " + ctx.attempt() + "/" + ctx.maxAttempts());
    ctx.reportProgress(0.5);
    if (ctx.isCancellationRequested()) return;
    // ...
}

Accessors​

AccessorTypeNotes
jobId()StringUnique per execution. Use it to dedupe (at-least-once delivery).
jobType()StringThe routing key this execution matched.
attempt()int1-based attempt counter.
maxAttempts()intConfigured maximum attempts.
enqueuedAt()Optional<OffsetDateTime>When the job was enqueued; empty if absent/unparseable (never throws).
cancellationToken()CancellationTokenThe cooperative cancellation handle. See Cancellation.
isCancellationRequested()booleanConvenience flag.
reportProgress(double)voidReport 0.0–1.0 progress.
logger()System.LoggerA logger bound to this job's id and type.

Reporting progress​

Call reportProgress(value) with a fraction from 0.0 to 1.0. The most recent value rides the next heartbeat to Flare and shows on the dashboard. The value is sanitised for you: anything above 1.0 is clamped to 1.0, and 0, negative, or NaN values are ignored (treated as "no update"). Progress is reported, not enforced to increase — Flare keeps the highest value it has seen, so a brief out-of-order report does no harm.

ctx.reportProgress(0.25);
// ... work ...
ctx.reportProgress(0.75);
// ... work ...
ctx.reportProgress(1.0);

Logging​

ctx.logger() is a standard System.Logger already tagged with the job's id and type, so your handler logs correlate automatically with the worker's own job events. Bind System.Logger to your logging backend (SLF4J, Log4j2, …) via the JDK service mechanism; with no binding it falls back to the platform logger. Never log the raw payload or secrets at INFO.

Last updated on