Kora Aop Scheduling Quartz

Kora Quartz Scheduling

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Annotate a method on a graph component with @ScheduleWithCron or @ScheduleWithTrigger. The processor generates a $<Class>_<method>_Job wrapper plus a $<Class>_SchedulingModule @Module; KoraQuartzJobRegistrar registers every generated job with the Quartz Scheduler at graph init.

This is not an AOP proxy. The generated job holds a reference to your component and calls the method directly, so the class may stay final (Java) / non-open (Kotlin) — the canonical examples do exactly that. open is only needed if you also stack a method-wrapping aspect (@Log, @Retryable, @Timeout) on the same class.

Quick start

1. Dependencies

// build.gradle (Java)
dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")   // koraVersion=2.0.0.RC1
    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:scheduling-quartz"
    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:logging-logback"
}

// build.gradle.kts (Kotlin)
dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")

    implementation("io.koraframework:scheduling-quartz")
    implementation("io.koraframework:config-hocon")
    implementation("io.koraframework:logging-logback")
}

2. Plug the module into @KoraApp

import io.koraframework.application.graph.KoraApplication;
import io.koraframework.common.annotation.KoraApp;
import io.koraframework.config.hocon.HoconConfigModule;
import io.koraframework.logging.logback.LogbackModule;
import io.koraframework.scheduling.quartz.QuartzModule;

@KoraApp
public interface Application extends HoconConfigModule, LogbackModule, QuartzModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

3. A cron job

import io.koraframework.common.annotation.Component;
import io.koraframework.scheduling.quartz.ScheduleWithCron;

@Component
public final class CronScheduler {

    @ScheduleWithCron("0 0 3 * * ?")   // daily at 03:00
    void nightlyReport() {
        // ...
    }
}

The method must be reachable from the generated code, which lands in the same package — package-private (Java) / internal or public (Kotlin) is enough.

What's in this skill

Quartz or JDK?

Both modules ship a @ScheduleWithCron in Kora 2.0 — they are different annotations in different packages and route to different schedulers:

Importing the wrong one compiles and silently schedules the job on the other engine. Check the import, not the simple name.

Annotations

@DisallowConcurrentExecution and @PersistJobDataAfterExecution are Kora's own annotations in io.koraframework.scheduling.quartz — not re-exports. The generators also accept the Quartz originals (org.quartz.DisallowConcurrentExecution, org.quartz.PersistJobDataAfterExecution), but only on the class; the Kora ones are read on the method only. Either form ends up as the org.quartz.* annotation on the generated job class.

@ScheduleWithTrigger — the 2.0 signature

@KoraApp
public interface Application extends QuartzModule {

    @Tag(TriggerScheduler.class)
    default Trigger myTrigger() {
        return TriggerBuilder.newTrigger()
            .withIdentity("myTrigger")
            .startNow()
            .withSchedule(SimpleScheduleBuilder.simpleSchedule()
                .withIntervalInSeconds(5)
                .repeatForever())
            .build();
    }
}

@Component
public final class TriggerScheduler {

    @ScheduleWithTrigger(TriggerScheduler.class)   // class tag passed directly
    void schedule() { }
}

@ScheduleWithTrigger(TriggerScheduler::class)
fun schedule() { }

The class you pass becomes a @Tag on the org.quartz.Trigger parameter of the generated factory method, so the graph must contain a Trigger under exactly that tag. The convention is to tag with the job class itself.

Kora 1.x wrote @ScheduleWithTrigger(@Tag(MyJob.class)). In 2.0 the attribute is Class<?>, so the nested form fails at compile time: error: annotation not valid for an element of type Class<?>.

@ScheduleWithCron

@ScheduleWithCron("0 0 9 ? * MON-FRI")                 // 09:00 on weekdays
void morningReport() { }

@ScheduleWithCron(value = "0 0 * * * ?", identity = "hourly")
void hourly() { }

@ScheduleWithCron(config = "jobs.nightly")             // cron comes from config
void nightly() { }

Quartz cron is the 6- or 7-field form (sec min hour day-of-month month day-of-week [year]); day-of-month and day-of-week are mutually exclusive, so one of them must be ?.

With config, the node may be a bare string (jobs.nightly = "0 0 3 * * ?") or an object with a cron field. If value is also set it is the fallback used when the config node is absent; if value is empty the config node is required and a missing one fails the graph build. Only the config form supports per-job telemetry overrides. See scheduling-config-reference.md.

Contracts

• Synchronous only. A scheduled method returns void / Unit and takes either no arguments or a single org.quartz.JobExecutionContext.
• Kotlin suspend is rejected by KSP: "Suspend methods are not supported by the scheduling generator" — the message points at StructuredTaskScope for real parallelism.
• Mono/Flux/CompletionStage are not Kora 2.0 contracts anywhere, scheduling included. Context no longer exists in the framework; use the JobExecutionContext argument for Quartz fire-time data.
• The enclosing class must be a graph component (@Component, or supplied by a @Module factory method) — the generated module takes it as a constructor dependency.

Thread model

Quartz jobs do not run on Kora's virtual threads. KoraQuartzScheduler builds a plain StdSchedulerFactory, so jobs run on Quartz's own SimpleThreadPool: platform threads named kora-quartz-scheduler_Worker-N, org.quartz.threadPool.threadCount = 10 by default, non-daemon. That thread count is the hard ceiling on concurrent job executions across the whole application; oversubscribing it delays firings and produces misfires.

Kora still binds its own context around the call — KoraQuartzJob.execute installs the Kora MDC, a fresh OpenTelemetry context and the scheduling Observation before invoking your method, so logging and tracing work normally inside the job body.

Configuration essentials

scheduling {
  quartz {
    # raw org.quartz.* properties, passed to StdSchedulerFactory
    properties {
      "org.quartz.threadPool.threadCount" = "10"
    }
    waitForJobComplete = true   # default true — shutdown blocks until running jobs finish
  }

  telemetry {
    logging.enabled = true      # default false
    metrics.enabled = true      # default false
    tracing.enabled = true      # default true
  }
}

Kora forces org.quartz.scheduler.instanceName = kora-quartz-scheduler and org.quartz.scheduler.instanceId = AUTO as defaults — both are overridable from scheduling.quartz.properties. Everything else comes from the org/quartz/quartz.properties bundled in the Quartz jar (SimpleThreadPool, RAMJobStore, misfireThreshold = 60000).

Keys that no longer exist. The 1.x root quartz { "org.quartz.*" } block and scheduling.waitForJobComplete are not read by 2.0. Unknown HOCON keys are ignored without a warning, so a stale config starts green on Quartz defaults instead of your settings. Full table in scheduling-config-reference.md.

Shutdown — there is no interrupt

KoraQuartzScheduler.release() calls Scheduler.shutdown(waitForJobComplete). Quartz's SimpleThreadPool.shutdown(...) only clears a run flag on its workers — a busy worker is never interrupted, and Quartz documents it as "Jobs currently in progress will complete."

So Thread.currentThread().isInterrupted() inside a Kora Quartz job is dead code: it never becomes true because of shutdown. waitForJobComplete = false does not cancel anything either; it only stops release() from blocking, and the non-daemon worker keeps running. Kora's generated job class is final and KoraQuartzJob.execute is final, so it cannot implement org.quartz.InterruptableJob and Scheduler.interrupt(...) cannot reach it.

Bound the work inside the job body instead (deadline or batch cap) and make jobs idempotent and restartable. Note the Quartz wait has no timeout of its own — unlike scheduling-jdk, which caps it at scheduling.jdk.shutdownWait (30s) and then calls shutdownNow(), so isInterrupted() does work there. Shutdown is not shared code: scheduling-common carries only config and telemetry. Patterns and the full contrast in graceful-shutdown-reference.md.

Error handling

KoraQuartzJob.execute records the failure on the observation and rethrows, so the exception reaches Quartz and the trigger's misfire/refire policy applies. With scheduling.telemetry.logging.enabled = true Kora logs it at WARN with exceptionType and exceptionMessage. Catch inside the method if a failure should not surface as a Quartz job failure.

Common pitfalls

Related skills

• kora-aop-scheduling-jdk — fixed rate/delay/once and JDK cron
• kora-aop-logging — @Log on a scheduled method (that one does need open)
• kora-config-hocon — typed config for externalised cron
• kora-telemetry-metrics — enabling the metrics that scheduling reports