Kora Aop Scheduling Jdk

Kora AOP Scheduling (JDK)

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Artifact: ru.tinkoff.kora:scheduling-jdk Module: SchedulingJdkModule Annotation package: ru.tinkoff.kora.scheduling.jdk.annotation.*

Aspect-driven scheduling on top of the JVM ScheduledExecutorService. The annotations mirror the scheduleAtFixedRate, scheduleWithFixedDelay, and schedule method signatures. No external scheduler, no persistence — jobs live only for the lifetime of the process. For cron, persistent state, custom triggers, or cluster-wide single execution, use the sibling skill kora-aop-scheduling-quartz.

Aspect requirement: the bearing class must be non-final (Java) / open (Kotlin), otherwise the annotation processor cannot generate the scheduling aspect.

Quick Start

1. Add dependency

All Kora artifacts inherit their version from the kora-parent BOM — never version individual ru.tinkoff.kora:* deps.

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"   // mandatory — generates the aspect

    implementation "ru.tinkoff.kora:scheduling-jdk"
    implementation "ru.tinkoff.kora:config-hocon"
    implementation "ru.tinkoff.kora:logging-logback"
}

Kotlin uses ksp "ru.tinkoff.kora:symbol-processors" instead of annotationProcessor.

2. Plug the module into @KoraApp

@KoraApp
public interface Application extends
    HoconConfigModule,
    LogbackModule,
    SchedulingJdkModule {
}

3. Declare a scheduled component

package com.example.app.jobs;

import ru.tinkoff.kora.common.Component;
import ru.tinkoff.kora.scheduling.jdk.annotation.ScheduleAtFixedRate;
import java.time.temporal.ChronoUnit;

@Component
public class ScheduledJobs {   // non-final: required for aspect generation

    @ScheduleAtFixedRate(initialDelay = 30, period = 60, unit = ChronoUnit.SECONDS)
    void heartbeat() {
        // Lightweight task every 60 seconds
    }
}

JDK Annotations

@ScheduleAtFixedRate

Runs at fixed intervals. If task takes longer than period, next execution starts immediately after completion.

@ScheduleAtFixedRate(initialDelay = 30, period = 60, unit = ChronoUnit.SECONDS)
void heartbeat() {
    // Runs every 60s (may overlap if task > 60s)
}

@ScheduleWithFixedDelay

Waits for delay after task completion. No overlap possible.

@ScheduleWithFixedDelay(initialDelay = 30, delay = 60, unit = ChronoUnit.SECONDS)
void syncData() {
    // Completes → wait 60s → run again
}

@ScheduleOnce

Single execution after specified delay.

@ScheduleOnce(delay = 5, unit = ChronoUnit.MINUTES)
void warmup() {
    // Runs once after 5 minutes
}

Externalized parameters (config)

When the config attribute is set, the values come from that config path and override the annotation attributes (which then act only as defaults). The path is arbitrary; the example app nests jobs under scheduling.jobs.*.

@ScheduleAtFixedRate(config = "scheduling.jobs.heartbeat")
void heartbeat() { ... }

scheduling.jobs.heartbeat {
  initialDelay = "10s"
  period = "30s"
}

Keys per annotation: @ScheduleAtFixedRate → initialDelay, period; @ScheduleWithFixedDelay → initialDelay, delay; @ScheduleOnce → delay. Durations accept HOCON time strings ("5ms", "30s", "2m").

Module configuration

Defaults shown match ScheduledExecutorServiceConfig:

scheduling {
  threads = 2                    # ScheduledExecutorService pool size (default: 2)
  shutdownWait = "30s"           # grace period for in-flight jobs on graceful shutdown
  telemetry {
    logging.enabled = false      # job execution logging (default: false)
    metrics.enabled = true       # Micrometer metrics (default: true)
    tracing.enabled = true       # OpenTelemetry tracing (default: true)
  }
}

See scheduling-config-reference.md for SLO buckets, metric tags, and tracing attributes.

Graceful Shutdown

Long-running jobs must check interrupt status:

@ScheduleWithFixedDelay(config = "scheduling.jobs.batch")
void processBatch() {
    while (!stopCondition()) {
        if (Thread.currentThread().isInterrupted()) {
            return;  // Exit on shutdown signal
        }
        doWork();
    }
}

Error Handling

Exception is logged, next invocation continues normally.

Pattern: Wrap in try-catch to prevent logging noise.

@ScheduleAtFixedRate(period = 60, unit = ChronoUnit.SECONDS)
void process() {
    try {
        doWork();
    } catch (Exception e) {
        log.error("Scheduled task failed", e);
    }
}

Common Pitfalls

References, assets, scripts

For cron expressions, custom triggers, and persistent/clustered jobs, use the sibling skill kora-aop-scheduling-quartz.

Source of truth: .kora-agent/kora-docs/mkdocs/docs/en/documentation/scheduling.md (section #native) and .kora-agent/kora-examples/examples/java/kora-java-scheduling-jdk.

Related skills

• kora-aop-scheduling-quartz — cron, triggers, persistent and clustered jobs
• kora-aop-logging — @Log / @Mdc for scheduled methods