Планировщик

Модуль для создания планировщиков в декларативном стиле с помощью аннотаций.

Нативный

Создание планировщика с использованием стандартного ScheduledExecutorService который поставляется с JVM.

Для создания планировщика через аспекты используются специальные аннотации которые по сути дублируются сигнатуры методов ScheduledExecutorService. Параметры аннотаций соответствуют параметрам методов scheduleAtFixedRate, schedule, scheduleWithFixedDelay соответственно.

Так же все аннотации имеют аргумент config при наличии которого значения параметра возьмутся из конфигурации по указанному пути.

Подключение

Java Kotlin

Зависимость build.gradle:

implementation "ru.tinkoff.kora:scheduling-jdk"

Модуль:

@KoraApp
public interface Application extends SchedulingJdkModule { }

Зависимость build.gradle.kts:

implementation("ru.tinkoff.kora:scheduling-jdk")

Модуль:

@KoraApp
interface Application : SchedulingJdkModule

Конфигурация

Пример полной конфигурации, описанной в классе ScheduledExecutorServiceConfig (указаны значения по умолчанию):

Hocon YAML

scheduling {
    threads = 2 //(1)!
    shutdownWait = "30s" //(2)!
    telemetry {
        logging {
            enabled = false //(3)!
        }
        metrics {
            enabled = true //(4)!
            slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(5)!
        }
        tracing {
            enabled = true //(6)!
        }
    }
}

1. Максимальное кол-во потоков у ScheduledExecutorService
2. Время ожидания выполнения задач перед выключением планировщика в случае штатного завершения
3. Включает логгирование модуля (по умолчанию false)
4. Включает метрики модуля (по умолчанию true)
5. Настройка SLO для DistributionSummary метрики
6. Включает трассировку модуля (по умолчанию true)

scheduling:
  threads: 2 #(1)!
  shutdownWait: "30s" #(2)!
  telemetry:
    logging:
      enabled: false #(3)!
    metrics:
      enabled: true #(4)!
      slo: [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(5)!
    telemetry:
      enabled: true #(6)!

1. Максимальное кол-во потоков у ScheduledExecutorService
2. Время ожидания выполнения задач перед выключением планировщика в случае штатного завершения
3. Включает логгирование модуля (по умолчанию false)
4. Включает метрики модуля (по умолчанию true)
5. Настройка SLO для DistributionSummary метрики
6. Включает трассировку модуля (по умолчанию true)

Фиксированный интервал

Планирование с запуском через фиксированные промежутки времени.

Например, если период установлен в 10 секунд, а каждое выполнение задачи занимает 5 секунд, то задача будет выполняться каждые 10 секунд.

Но если выполнение задачи занимает больше времени, чем заданный период, следующее выполнение начнется только после завершения текущего. Выполнения нескольких задач не будут происходить одновременно.

Java Kotlin

@Component
public class SomeService {

    @ScheduleAtFixedRate(initialDelay = 50, period = 50, unit = ChronoUnit.MILLIS)
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleAtFixedRate(initialDelay = 50, period = 50, unit = ChronoUnit.MILLIS)
    fun schedule() {
        // do something
    }
}

Конфигурация

Возможно передача параметров через конфигурацию, она имеет приоритет перед указанными в аннотации параметрами:

Java Kotlin

@Component
public class SomeService {

    @ScheduleAtFixedRate(config = "job")
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleAtFixedRate(config = "job")
    fun schedule() {
        // do something
    }
}

Пример конфигурации через файл:

Hocon YAML

job {
    initialDelay = "50ms" //(1)!
    period = "50ms" //(2)!
}

1. Начальный интервал задержки перед первой задачей
2. Переодический интервал между задачами

job:
  initialDelay: "50ms" #(1)!
  period: "50ms" #(2)!

1. Начальный интервал задержки перед первой задачей
2. Переодический интервал между задачами

Фиксированная задержка

Ожидает фиксированный промежуток времени от конца предыдущего исполнения задачи перед началом следующего выполнения.

Не имеет значения, сколько времени занимает текущее исполнение, следующее выполнение запускается ровно после завершения предыдущей задачи и заданного промежутка ожидания между задачами.

Java Kotlin

@Component
public class SomeService {

    @ScheduleWithFixedDelay(initialDelay = 50, delay = 50, unit = ChronoUnit.MILLIS)
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleWithFixedDelay(initialDelay = 50, delay = 50, unit = ChronoUnit.MILLIS)
    fun schedule() {
        // do something
    }
}

Конфигурация

Возможно передача параметров через конфигурацию, она имеет приоритет перед указанными в аннотации параметрами:

Java Kotlin

@Component
public class SomeService {

    @ScheduleWithFixedDelay(config = "job")
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleWithFixedDelay(config = "job")
    fun schedule() {
        // do something
    }
}

Пример конфигурации через файл:

Hocon YAML

job {
    initialDelay = "50ms" //(1)!
    delay = "50ms" //(2)!
}

1. Начальный интервал задержки перед первой задачей
2. Переодический интервал задержки между задачами

job:
  initialDelay: "50ms" #(1)!
  delay: "50ms" #(2)!

1. Начальный интервал задержки перед первой задачей
2. Переодический интервал задержки между задачами

Одноразовый

Запускает одиножды задачу через определенный фиксированный интервал времени.

Java Kotlin

@Component
public class SomeService {

    @ScheduleOnce(delay = 50, unit = ChronoUnit.MILLIS)
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleOnce(delay = 50, unit = ChronoUnit.MILLIS)
    fun schedule() {
        // do something
    }
}

Конфигурация

Возможно передача параметров через конфигурацию, она имеет приоритет перед указанными в аннотации параметрами:

Java Kotlin

@Component
public class SomeService {

    @ScheduleOnce(config = "job")
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleOnce(config = "job")
    fun schedule() {
        // do something
    }
}

Пример конфигурации через файл:

Hocon YAML

job {
    delay = "50ms" //(1)!
}

1. Начальный интервал задержки перед задачей

job:
  delay: "50ms" #(1)!

1. Начальный интервал задержки перед задачей

Штатное завершение

Если вы хотите предварительно завершить обработку при штатном завершении сервиса не дожидаясь ее окончания, требуется проверять Thread.currentThread().isInterrupted() статус и прекращать работу самостоятельно.

Quartz

Реализация на основе библиотеки Quartz как планировщика для создания аспектов.

Подключение

Java Kotlin

Зависимость build.gradle:

implementation "ru.tinkoff.kora:scheduling-quartz"

Модуль:

@KoraApp
public interface Application extends QuartzModule { }

Зависимость build.gradle.kts:

implementation("ru.tinkoff.kora:scheduling-quartz")

Модуль:

@KoraApp
interface Application : QuartzModule

Конфигурация

Конфигурация указывается как значения Properties в формате ключ и значение:

Hocon YAML

quartz { //(1)!
    "org.quartz.threadPool.threadCount" = "10"
}
scheduling {
    waitForJobComplete = true //(2)!
    telemetry {
        logging {
            enabled = false //(3)!
        }
        metrics {
            enabled = true //(4)!
            slo = [ 1, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] //(5)!
        }
        tracing {
            enabled = true //(6)!
        }
    }
}

1. Параметры настройки Quartz планировщика
2. Ожидать ли выполнения задач перед выключением планировщика в случае штатного завершения
3. Включает логгирование модуля (по умолчанию false)
4. Включает метрики модуля (по умолчанию true)
5. Настройка SLO для DistributionSummary метрики
6. Включает трассировку модуля (по умолчанию true)

quartz: #(1)!
  org.quartz.threadPool.threadCount: "10"
scheduling:
  waitForJobComplete: true #(2)!
  telemetry:
    logging:
      enabled: false #(3)!
    metrics:
      enabled: true #(4)!
      slo: [ 3, 10, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 30000, 60000, 90000 ] #(5)!
    telemetry:
      enabled: true #(6)!

1. Параметры настройки Quartz планировщика
2. Ожидать ли выполнения задач перед выключением планировщика в случае штатного завершения
3. Включает логгирование модуля (по умолчанию false)
4. Включает метрики модуля (по умолчанию true)
5. Настройка SLO для DistributionSummary метрики
6. Включает трассировку модуля (по умолчанию true)

По умолчанию используются настройки из:

quartz.properties

org.quartz.scheduler.instanceName: DefaultQuartzScheduler
org.quartz.scheduler.rmi.export: false
org.quartz.scheduler.rmi.proxy: false
org.quartz.scheduler.wrapJobExecutionInUserTransaction: false

org.quartz.threadPool.class: org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount: 10
org.quartz.threadPool.threadPriority: 5
org.quartz.threadPool.threadsInheritContextClassLoaderOfInitializingThread: true

org.quartz.jobStore.misfireThreshold: 60000

org.quartz.jobStore.class: org.quartz.simpl.RAMJobStore

Крон

Использование Cron выражений для запуска запланированных задач.

Запускает одиножды задачу через определенный фиксированный интервал времени.

Java Kotlin

@Component
public class SomeService {

    @ScheduleWithCron("0 0 * * * * ?") //(1)!
    void schedule() {
        // do something
    }
}

1. Cron выражение говорящее запускать задачу каждый час и каждый день

@Component
class SomeService {

    @ScheduleWithCron("0 0 * * * * ?") //(1)!
    fun schedule() {
        // do something
    }
}

1. Cron выражение говорящее запускать задачу каждый час и каждый день

Конфигурация

Возможно передача параметров через конфигурацию, она имеет приоритет перед указанными в аннотации параметрами:

Java Kotlin

@Component
public class SomeService {

    @ScheduleWithCron(config = "job")
    void schedule() {
        // do something
    }
}

@Component
class SomeService {

    @ScheduleWithCron(config = "job")
    fun schedule() {
        // do something
    }
}

Пример конфигурации:

Hocon YAML

job {
    cron = "0 0 * * * * ?" //(1)!
}

1. Cron выражение говорящее запускать задачу каждый час и каждый день

job:
  cron: "0 0 * * * * ?" #(1)!

1. Cron выражение говорящее запускать задачу каждый час и каждый день

Триггер

Предполагает создание собственного триггера на основе библиотеки Quartz и регистрация его в контейнере приложения с определенным тегом и последующее его использование через аннотацию.

Java Kotlin

@KoraApp
public interface Application extends QuartzModule {

    @Tag(SomeService.class) //(1)!
    default Trigger myTrigger() {
        return TriggerBuilder.newTrigger()
                .withIdentity("myTrigger")
                .startNow()
                .withSchedule(SimpleScheduleBuilder.simpleSchedule()
                        .withIntervalInMilliseconds(50)
                        .repeatForever())
                .build();
    }
}

@Component
public class SomeService {

    @ScheduleWithTrigger(@Tag(SomeService.class)) //(2)!
    void schedule() {
        // do something
    }
}

1. Тег триггера
2. Тег триггера

@KoraApp
interface Application : QuartzModule {

    @Tag(SomeService::class) //(1)!
    fun myTrigger(): Trigger {
        return TriggerBuilder.newTrigger()
            .withIdentity("myTrigger")
            .startNow()
            .withSchedule(
                SimpleScheduleBuilder.simpleSchedule()
                    .withIntervalInMilliseconds(50)
                    .repeatForever()
            )
        .build()
    }
}

@Component
class SomeService {

    @ScheduleWithTrigger(@Tag(SomeService.class)) //(2)!
    fun schedule() {
        // do something
    }
}

1. Тег триггера
2. Тег триггера