Version:

Scheduler reference guide

最近のアプリケーションでは、特定のタスクを定期的に実行する必要があることがよくあります。Quarkusには、2つのスケジューラエクステンションがあります。 quarkus-scheduler エクステンションは、APIと軽量のインメモリスケジューラー実装を提供します。 quarkus-quartz エクステンションは、 quarkus-scheduler エクステンションのAPIを実装し、Quartzライブラリに基づくスケジューラ実装を含んでいます。 quarkus-quartz が必要になるのは、永続タスクやクラスタリングなど、より高度なスケジューリングのユースケースだけです。

If you add the quarkus-quartz dependency to your project the lightweight scheduler implementation from the quarkus-scheduler extension is automatically disabled.

1. スケジュールされたメソッド

@io.quarkus.scheduler.Scheduled でアノテーションされたメソッドは、自動的に呼び出しがスケジュールされます。スケジュールされたメソッドは、abstract または private であってはなりません。静的または非静的のいずれでもかまいません。スケジュールされたメソッドには、@jakarta.transaction.Transactional のようなインターセプターバインディングをアノテーションできます。

If there is a bean class that has no scope and declares at least one non-static method annotated with @Scheduled then @Singleton is used.

さらに、アノテーションされたメソッドは void を返し、パラメーターを宣言しないか、 io.quarkus.scheduler.ScheduledExecution 型のパラメーターを 1 つだけ宣言する必要があります。

The annotation is repeatable so a single method could be scheduled multiple times.

1.1. メタデータの継承

サブクラスは、スーパークラスで宣言された @Scheduled メソッドのメタデータを継承しません。たとえば、クラス org.amce.Foo がクラス org.amce.Bar によって拡張されているとします。 Foo が @Scheduled アノテーションが付けられた非静的メソッドを宣言する場合、 Bar はスケジュールされたメソッドのメタデータを継承しません。次の例では、 everySecond() メソッドは Foo のインスタンスに対してのみ呼び出されます。

class Foo {

   @Scheduled(every = "1s")
   void everySecond() {
     // ..do something
   }
}

@Singleton
class Bar extends Foo {
}

1.2. CDI イベント

一部の CDI イベントは、特定のイベントが発生したときに同期的または非同期的に起動されます。

タイプイベントの説明

タイプ	イベントの説明
`io.quarkus.scheduler.StartedExecution`	An execution of a scheduled job was started.
`io.quarkus.scheduler.SuccessfulExecution`	スケジュールされたジョブの実行が正常に完了しました。
`io.quarkus.scheduler.FailedExecution`	スケジュールされたジョブの実行が例外を伴って完了しました。
`io.quarkus.scheduler.SkippedExecution`	スケジュールされたジョブの実行がスキップされました。
`io.quarkus.scheduler.DelayedExecution`	An execution of a scheduled job was delayed.
`io.quarkus.scheduler.SchedulerPaused`	スケジューラーが一時停止されました。
`io.quarkus.scheduler.SchedulerResumed`	スケジューラーが再開されました。
`io.quarkus.scheduler.ScheduledJobPaused`	スケジュールされたジョブが一時停止されました。
`io.quarkus.scheduler.ScheduledJobResumed`	スケジュールされたジョブが再開されました。

io.quarkus.scheduler.StartedExecution

An execution of a scheduled job was started.

io.quarkus.scheduler.SuccessfulExecution

スケジュールされたジョブの実行が正常に完了しました。

io.quarkus.scheduler.FailedExecution

スケジュールされたジョブの実行が例外を伴って完了しました。

io.quarkus.scheduler.SkippedExecution

スケジュールされたジョブの実行がスキップされました。

io.quarkus.scheduler.DelayedExecution

An execution of a scheduled job was delayed.

io.quarkus.scheduler.SchedulerPaused

スケジューラーが一時停止されました。

io.quarkus.scheduler.SchedulerResumed

スケジューラーが再開されました。

io.quarkus.scheduler.ScheduledJobPaused

スケジュールされたジョブが一時停止されました。

io.quarkus.scheduler.ScheduledJobResumed

スケジュールされたジョブが再開されました。

1.3. トリガー

トリガーは、 @Scheduled#cron() 属性または @Scheduled#every() 属性によって定義されます。両方が指定されている場合、cron 式が優先されます。何も指定されていない場合、ビルドは IllegalStateException で失敗します。

1.3.1. CRON

CRONトリガーは、cronライクな式で定義されています。例えば "0 15 10 * * ?" は毎日午前10時15分に起動します。

CRON Trigger Example

@Scheduled(cron = "0 15 10 * * ?")
void fireAt1015AmEveryDay() { }

CRON 式で使用される構文は quarkus.scheduler.cron-type プロパティーによって制御されます。値は cron4j , quartz , unix および spring のいづれかです。 quartz がデフォルトで使用されます。

cron 属性は、デフォルト値とネストされた値プロパティー式を含むProperty Expressions をサポートします。 ("{property.path}" スタイルの式は引き続きサポートされますが、プロパティー式の機能がすべて提供されるわけではありません。)

CRON Config Property Example

@Scheduled(cron = "${myMethod.cron.expr}")
void myMethod() { }

特定のスケジュールメソッドを無効にしたい場合は、そのcron式を "off" または "disabled" に設定します。

application.properties

myMethod.cron.expr=disabled

プロパティ式では、そのプロパティが構成されていない場合に使用されるデフォルト値を定義することができます。

CRON Config Property Example with default 0 0 15 ? * MON *

@Scheduled(cron = "${myMethod.cron.expr:0 0 15 ? * MON *}")
void myMethod() { }

プロパティ myMethod.cron.expr が未定義または null の場合は、デフォルト値（ 0 0 15 ? * MON * ）が使用されます。

1.3.1.1. タイムゾーン

cron式は、デフォルトのタイムゾーンのコンテキストで評価されます。しかし、cron式を特定のタイムゾーンに関連付けることも可能です。

Time Zone Example

@Scheduled(cron = "0 15 10 * * ?", timeZone = "Europe/Prague") (1)
void myMethod() { }

1	タイムゾーンIDは、 `java.time.ZoneId#of(String)` を使って解析されます。

timeZone 属性はデフォルト値とネストされた値のプロパティー式を含む Property Expressions をサポートします。

Time Zone Configuration Property Example

@Scheduled(cron = "0 15 10 * * ?", timeZone = "${myMethod.timeZone}")
void myMethod() { }

1.3.2. インターバル

インターバルトリガーは、次の呼び出しまでの期間を定義します。期間の表現は ISO-8601 期間形式 PnDTnHnMn.nS に基づいており、 @Scheduled#every() の値は java.time.Duration#parse (CharSequence) で解析されます。ただし、式が数字で始まり、 d で終わる場合、 P 接頭辞が自動的に追加されます。式が数字でのみ始まる場合、 PT 接頭辞が自動的に追加されます。たとえば、 PT15M の代わりに 15m を使用すると、15 分として解析されます。

Interval Trigger Example

@Scheduled(every = "15m")
void every15Mins() { }

A value less than one second may not be supported by the underlying scheduler implementation. In that case a warning message is logged during build and application start.

every 属性は、デフォルト値とネストされた値プロパティー式を含むProperty Expressions をサポートします。 ("{property.path}" スタイルの式は引き続きサポートされますが、プロパティー式の機能がすべて提供されるわけではありません。)

Interval Config Property Example

@Scheduled(every = "${myMethod.every.expr}")
void myMethod() { }

Intervals は、その値を "off" または "disabled" に設定することで無効にすることができます。そのため、例えば、デフォルト値 "off" のプロパティ式は、そのConfig Propertyが設定されていない場合、トリガーを無効にするために使用することができます。

Interval Config Property Example with a Default Value

@Scheduled(every = "${myMethod.every.expr:off}")
void myMethod() { }

1.4. アイデンティティ

デフォルトでは、スケジュールされた各メソッドに対して一意の ID が生成されます。このIDはログメッセージやデバッグ中に使用されます。時には、明示的な id を指定することが便利な場合もあります。

Identity Example

@Scheduled(identity = "myScheduledMethod")
void myMethod() { }

identity 属性は、デフォルト値とネストされた値プロパティー式を含むProperty Expressions をサポートします。 ("{property.path}" スタイルの式は引き続きサポートされますが、プロパティー式の機能がすべて提供されるわけではありません。)

Interval Config Property Example

@Scheduled(identity = "${myMethod.identity.expr}")
void myMethod() { }

1.5. 説明

An optional description can be attached to a scheduled method to document what the job does.

Description Example

@Scheduled(every = "1s", description = "Checks the status of external services")
void checkStatus() { }

The description attribute supports Property Expressions including default values and nested Property Expressions. (Note that "{property.path}" style expressions are still supported but don’t offer the full functionality of Property Expressions.)

Description Config Property Example

@Scheduled(every = "1s", description = "${myJob.description}")
void checkStatus() { }

When using the Quartz extension with a JDBC job store, the description is limited to 250 characters due to database column constraints.

1.6. トリガーの遅延開始

@Scheduled では、トリガーが発報を開始時刻を遅らせるための2つの方法を提供しています。

@Scheduled#delay() と @Scheduled#delayUnit() は初期遅延を一緒に形成します。

@Scheduled(every = "2s", delay = 2, delayUnit = TimeUnit.HOUR) (1)
void everyTwoSeconds() { }

1	アプリケーション開始から2時間後に初めてトリガーが発射されます。

The final value is always rounded to full second.

@Scheduled#delayed() は、上記のプロパティーの代替テキストです。期間の表現は ISO-8601 の期間形式 PnDTnHnMn.nS に基づいており、値は java.time.Duration#parse (CharSequence) で解析されます。ただし、式が数字で始まり、 d で終わる場合、 P の接頭辞が自動的に追加されます。式が数字だけで始まる場合、 PT 接頭辞が自動的に追加されます。たとえば、 PT15S の代わりに 15s を使用すると、15 秒として解析されます。

@Scheduled(every = "2s", delayed = "2h")
void everyTwoSeconds() { }

If @Scheduled#delay() is set to a value greater than zero the value of @Scheduled#delayed() is ignored.

@Scheduled#delay() と比較した場合の主な利点は、値が設定可能であることです。 delay 属性は、デフォルト値やネストされたプロパティ式を含む Property Expressions をサポートしています。(なお、 "{property.path}" スタイルの表現はサポートされていますが、プロパティ式の完全な機能は提供されていません)。

@Scheduled(every = "2s", delayed = "${myMethod.delay.expr}") (1)
void everyTwoSeconds() { }

1	遅延の設定には、configプロパティー `myMethod.delay.expr` を使用します。

1.7. 遅延実行

@Scheduled#executionMaxDelay() を設定すると、スケジュールされたメソッドの各実行を遅延できます。この値は、トリガーのアクティブ化とスケジュールされたメソッドの実行との間の最大遅延を表します。実際の遅延は、0 から指定された最大遅延までの間でランダムに生成された数値です。

値は DurationConverter#parseDuration (String) で解析されます。これはプロパティー式である可能性があり、その場合、スケジューラーは代わりに設定された値 (@Scheduled (executionMaxDelay = "${myJob.maxDelay}")) を使用しようとします。さらに、プロパティー式ではデフォルト値 (@Scheduled (実行最大遅延 = "${myJob.maxDelay}:500ms}")) を指定できます。

@Scheduled(every = "2s", executionMaxDelay = "500ms") (1)
void everyTwoSeconds() { }

1	遅延の値は 0 - 500 ミリ秒です。その結果、 `everyTwoSeconds()` 実行間隔は、およそ 1.5 - 2.5 秒です。

1.8. 同時実行

デフォルトでは、スケジュールされたメソッドは同時に実行することができます。それにもかかわらず、 @Scheduled#concurrentExecution() を通じて同時実行を処理するための戦略を指定することが可能です。

import static io.quarkus.scheduler.Scheduled.ConcurrentExecution.SKIP;

@Scheduled(every = "1s", concurrentExecution = SKIP) (1)
void nonConcurrent() {
  // we can be sure that this method is never executed concurrently
}

1	同時実行はスキップされます。

A CDI event of type io.quarkus.scheduler.SkippedExecution is fired when an execution of a scheduled method is skipped.

Note that only executions within the same application instance are considered. This feature is not intended to work across the cluster.

1.9. 条件付き実行

@Scheduled#skipExecutionIf() を使用して、スケジュールされたメソッドの実行をスキップするロジックを定義できます。指定されたクラスは io.quarkus.scheduler.Scheduled.SkipPredicate を実装する必要があり、 test() メソッドの結果が true の場合、実行はスキップされます。クラスは CDI Bean を表すか、引数なしのパブリックコンストラクターを宣言する必要があります。 CDI の場合、Bean タイプのセット内に指定されたクラスを持つ Bean が 1 つだけ存在する必要があります。そうでない場合、ビルドは失敗します。さらに、ジョブの実行中は Bean のスコープがアクティブである必要があります。スコープが @Dependent の場合、Bean インスタンスは特定のスケジュールメソッドだけに属し、アプリケーションがシャットダウンされると破棄されます。

class Jobs {

   @Scheduled(every = "1s", skipExecutionIf = MyPredicate.class) (1)
   void everySecond() {
     // do something every second...
   }
}

@Singleton (2)
class MyPredicate implements SkipPredicate {

   @Inject
   MyService service;

   boolean test(ScheduledExecution execution) {
       return !service.isStarted(); (3)
   }
}

1	`MyPredicate.class` の Bean インスタンスは、実行をスキップすべきかどうかを評価するために使用されます。Beanタイプのセットに指定されたクラスを持つBeanが正確に1つ存在する必要があり、そうでない場合はビルドが失敗します。
2	Beanのスコープは、実行中を通じてアクティブです。
3	`Jobs.everySecond()` は、 `MyService.isStarted()` が `true` を返すまでスキップされます。

なお、これは以下のコードと同等のものです:

class Jobs {

   @Inject
   MyService service;

   @Scheduled(every = "1s")
   void everySecond() {
     if (service.isStarted()) {
        // do something every second...
     }
   }
}

主なアイデアは、スケジュールされたビジネスメソッドの外で実行をスキップするロジックを維持することで、再利用やリファクタリングが容易にできるようにすることです。

A CDI event of type io.quarkus.scheduler.SkippedExecution is fired when an execution of a scheduled method is skipped.

To skip the scheduled executions while the application is starting up/shutting down, you can make use of the io.quarkus.scheduler.Scheduled.ApplicationNotRunning skip predicate.

1.10. ノンブロッキング方式

デフォルトでは、スケジュールされたメソッドは、ブロックするタスクのメインエクゼキュータ上で実行されます。そのため、Vert.xイベントループ上で実行するように設計された技術（Hibernate Reactiveなど）は、メソッド本体内で使用することができません。このため、 java.util.concurrent.CompletionStage<Void> または io.smallrye.mutiny.Uni<Void> を返す、あるいは @io.smallrye.common.annotation.NonBlocking でアノテーションされたスケジュール型メソッドは、代わりに Vert.x のイベントループで実行されます。

class Jobs {

   @Scheduled(every = "1s")
   Uni<Void> everySecond() { (1)
     // ...do something async
   }
}

1	リターンタイプ `Uni<Void>` は、Vert.xのイベントループでメソッドを実行するようにスケジューラに指示します。

1.11. 複数のスケジューラー実装を使用する方法

場合によっては、スケジュールされたメソッドを実行するために使用されるスケジューラー実装を選択すると便利な場合があります。ただし、デフォルトでは、すべてのスケジュールされたメソッドに対して 1 つの Scheduler 実装のみが使用されます。たとえば、 quarkus-quartz エクステンションはクラスタリングをサポートするスケジューラ実装を提供しますが、その代わりにシンプルなインメモリー実装は使用できなくなります。そのため、クラスタリングが有効になっている場合、単一のノードでローカルに実行されるスケジュールされたメソッドを定義できません。ただし、 quarkus.scheduler.use-composite-scheduler 設定プロパティーを true に設定すると、代わりに複合 Scheduler が使用されます。つまり、複数のスケジューラー実装が並行して実行されます。さらに、 @Scheduled#executeWith() を使用して、スケジュールされたメソッドの実行に使用される特定の実装を選択することもできます。

class Jobs {

   @Scheduled(cron = "0 15 10 * * ?") (1)
   void fireAt10AmEveryDay() { }

   @Scheduled(every = "1s", executeWith = Scheduled.SIMPLE) (2)
   void everySecond() { }
}

1	`quarkus-quartz` エクステンションが存在する場合、このメソッドは Quartz 固有のスケジューラーで実行されます。
2	`quarkus.scheduler.use-composite-scheduler=true` が設定されている場合、このメソッドは `quarkus-scheduler` エクステンションによって提供される単純なインメモリー実装を使用して実行されます。

2. スケジューラー

Quarkusは、 io.quarkus.scheduler.Scheduler 型のビルトインBeanを提供しており、これを注入してスケジューラーを一時停止/再開するために使用することができます。

Scheduler Injection Example

import io.quarkus.scheduler.Scheduler;

class MyService {

   @Inject
   Scheduler scheduler;

   void ping() {
      scheduler.pause(); (1)
      scheduler.pause("myIdentity"); (2)
      if (scheduler.isRunning()) {
         throw new IllegalStateException("This should never happen!");
      }
      scheduler.resume("myIdentity"); (3)
      scheduler.resume(); (4)
      scheduler.getScheduledJobs(); (5)
      Trigger jobTrigger = scheduler.getScheduledJob("myIdentity"); (6)
      if (jobTrigger != null && jobTrigger.isOverdue()){ (7)
        // the job is late to the party.
      }
   }
}

1	すべてのトリガーを一時停止します。
2	スケジュールされた特定のメソッドをそのIDで一時停止する
3	スケジュールされた特定のメソッドを、そのIDで再開する
4	スケジューラーを再開します。
5	スケジューラーを再開します。
6	スケジュールされた特定のメソッドを、そのIDで再開する。
7	isOverdue()の猶予期間は、quarkus.scheduler.overdue-grace-periodを使用して設定することができます

A CDI event is fired synchronously and asynchronously when the scheduler or a scheduled job is paused/resumed. The payload is io.quarkus.scheduler.SchedulerPaused, io.quarkus.scheduler.SchedulerResumed, io.quarkus.scheduler.ScheduledJobPaused and io.quarkus.scheduler.ScheduledJobResumed respectively.

3. 長時間タスクのスケジューリング

長時間実行されるタスクを実行すると、次のような警告メッセージが表示されることがあります：

WARN  [io.ver.cor.imp.BlockedThreadChecker] (vertx-blocked-thread-checker) Thread Thread[vert.x-worker-thread-1,5,main] has been blocked for 81879 ms, time limit is 60000 ms: io.vertx.core.VertxException: Thread blocked

これは、デフォルトのワーカースレッドプールがVert.xから来たもので、スレッドがあまりにも長くブロックされるのを防ぐためです。

The amount of time for which a Vert.x worker thread can be blocked is also configurable.

したがって、長いタスクを実行する適切な方法は、スケジュールメソッドからカスタム実行サービスにオフロードすることです。以下は、頻繁に実行されるとは思っていない長時間タスクのセットアップの例です：

@ApplicationScoped
public class LongRunner implements Runnable {

    private ExecutorService executorService;

    @PostConstruct
    void init() {
        executorService = Executors.newThreadPerTaskExecutor(Executors.defaultThreadFactory()); (1)
    }

    @PreDestroy
    void destroy() {
        executorService.shutdown(); (2)
    }


    @Scheduled(cron = "{my.schedule}")
    public void update() {
        executorService.execute(this); (3)
    }

    @Override
    public void run() { (4)
        // perform the actual task here
    }
}

1	フィットするエクゼキューターを作成します。この場合、スケジュールされたタスクごとに新しいスレッドが作成され、タスクが終了すると停止します。
2	`@PreDestroy` コールバックは、executorサービスをシャットダウンするために使用されます。
3	スケジューリングされたメソッドは、ジョブをカスタムエグゼキュータに委譲するだけです。これにより、Vert.xスレッドがブロックされるのを防ぎます。
4	このBeanは `Runnable` を実装しています。これは、エグゼキュータ・サービスにパラメータとして直接渡せるフォーマットです。

4. プログラムスケジューリング

注入された io.quarkus.scheduler.Scheduler は、プログラム的にジョブをスケジュールするために使用することもできます。

Programmatic Scheduling

import io.quarkus.scheduler.Scheduler;

@ApplicationScoped
class MyJobs {

    @Inject
    Scheduler scheduler;

    void addMyJob() { (1)
        scheduler.newJob("myJob")
            .setCron("0/5 * * * * ?")
            .setTask(executionContext -> { (2)
                // do something important every 5 seconds
            })
            .schedule(); (3)
    }

    void removeMyJob() {
        scheduler.unscheduleJob("myJob"); (4)
    }
}

1	これは、 `@Scheduled(identity = "myJob", cron = "0/5 * * * * ?")` でアノテーションされたメソッドに代わるプログラム的な代替です。
2	ビジネスロジックはコールバックで定義されます。
3	`JobDefinition#schedule()` メソッドが呼び出されると、ジョブがスケジュールされます。
4	プログラムによって追加されたジョブも削除することができます。

By default, the scheduler is not started unless a @Scheduled business method is found. You may need to force the start of the scheduler for "pure" programmatic scheduling via quarkus.scheduler.start-mode=forced.

If the Quartz extension is present and the DB store type is used then it’s not possible to pass a task instance to the job definition and a task class must be used instead. The Quartz API can be also used to schedule a job programmatically.

場合によっては、詳細にわたるアプローチが必要になることがあります。そのため、Quarkus は CDI Bean として注入できる java.util.concurrent.ScheduledExecutorService と java.util.concurrent.ExecutorService も公開しています。ただし、これらのエグゼキューターは他の Quarkus エクステンションによって使用されるため、注意して使用する必要があります。さらに、ユーザーがこれらのエグゼキューターを手動でシャットダウンすることは許可されていません。

class JobScheduler {

   @Inject
   ScheduledExecutorService executor;

   void everySecondWithDelay() {
       Runnable myRunnable = createMyRunnable();
       executor.scheduleAtFixedRate(myRunnable, 3, 1, TimeUnit.SECONDS);
   }
}

5. スケジュールされたメソッドとテスト

テストを実行するときは、スケジューラーを無効にすることが望ましい場合がよくあります。スケジューラーは、ランタイム設定プロパティー quarkus.scheduler.enabled を通じて無効にできます。 false に設定すると、アプリケーションにスケジュールされたメソッドが含まれていても、スケジューラーは開始されません。特定のスケジューラー (Test Profiles) を無効にすることもできます。

5.1. Controlling the Scheduler in Tests

In a @QuarkusTest the scheduler normally starts after the test application bootstrap, which means that @Scheduled methods may be invoked before the test infrastructure is ready; for example, before @InjectMock has had a chance to install mocks. If a scheduled method depends on a CDI bean that is mocked in the test, the first invocations can observe the real bean instead of the mock.

To avoid this, start the scheduler in halted mode and resume it manually in each test method after all mocks are configured:

application.properties

%test.quarkus.scheduler.start-mode=halted

Test class

@QuarkusTest
class MyScheduledTest {

    @Inject
    Scheduler scheduler;

    @InjectMock
    MyService mock;

    @Test
    void testScheduledMethod() throws InterruptedException {
        Mockito.when(mock.doWork()).thenReturn("test-value");
        scheduler.resume(); (1)
        try {
            // ...assert scheduled behavior
        } finally {
            scheduler.pause(); (2)
        }
    }
}

1	Resume the scheduler after all mocks are configured so that `@Scheduled` methods only observe mocked beans.
2	Pause the scheduler again to prevent interference with subsequent test methods.

6. メトリクス

quarkus.scheduler.metrics.enabled が true に設定されていて、metrics エクステンションが存在する場合、いくつかの基本的なメトリクスがすぐに公開されます。

Micrometer エクステンションが存在する場合、すべての @Scheduled メソッドに @io.micrometer.core.annotation.Timed インターセプター・バインディングが自動的に追加され (すでに存在する場合を除く)、 scheduled.methods という名前の io.micrometer.core.instrument.Timer と scheduled.methods.running という名前の io.micrometer.core.instrument.LongTaskTimer が登録されます。宣言するクラスの修飾子名と @Scheduled メソッド名がタグとして使用されます。

7. OpenTelemetry Tracing

quarkus.scheduler.tracing.enabled を true に設定し、OpenTelemetry エクステンションが存在する場合、 @Scheduled アノテーションで定義されているか、プログラムでスケジュールされているかに関係なく、ジョブのアイデンティティをもとにした名前でスパンが自動的に作成されます。

8. 仮想スレッド上で @Scheduled メソッドを実行

@Scheduled でアノテーションされたメソッドは、 @RunOnVirtualThread でアノテーションすることもできます。この場合、メソッドは仮想スレッド上で呼び出されます。

メソッドは void を返す必要があり、Java ランタイムは仮想スレッドのサポートを提供する必要があります。詳細については、仮想スレッドガイドをお読みください。

9. スケジュールされたタスクへのユーザーとロールの割り当て

@Scheduled アノテーションが付けられたメソッドでは、@RunAsUser アノテーションを使用してタスク実行の SecurityIdentity を設定できます。@RunAsUser アノテーションは、スケジュールされたタスクでのみ機能します。

Example scheduled task with @RunAsUser

import io.quarkus.scheduler.Scheduled;
import io.quarkus.security.identity.RunAsUser;
import jakarta.annotation.security.RolesAllowed;
import jakarta.enterprise.context.ApplicationScoped;

class MyJob {

    @Inject
    MyService myService;

    @RunAsUser(user = "Alice", roles = "admin") (1)
    @Scheduled(every = "1s")
    void updateTask() {
        myService.update();   (2)
    }

}

@ApplicationScoped
class MyService {

    @RolesAllowed("admin")
    void update() { }

}

1	ユーザー `Alice` をスケジュールされた `updateTask` に割り当てます。
2	`MyService#update` メソッドの呼び出しは成功します。これは、設定されたユーザーが `admin` ロールを持っているためです。

The @RunAsUser annotation creates an identity for scheduled tasks. It does not temporarily replace the current identity.

10. 設定リファレンス

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能

Configuration property	タイプ	デフォルト
`quarkus.scheduler.cron-type` The syntax used in CRON expressions. Environment variable: `QUARKUS_SCHEDULER_CRON_TYPE` Show more	`cron4j`, `quartz`, `unix`, `spring`, `spring53`	`quartz`
`quarkus.scheduler.metrics.enabled` Scheduled task metrics will be enabled if a metrics extension is present and this value is true. Environment variable: `QUARKUS_SCHEDULER_METRICS_ENABLED` Show more	boolean	`false`
`quarkus.scheduler.tracing.enabled` Controls whether tracing is enabled. If set to true and the OpenTelemetry extension is present, tracing will be enabled, creating automatic Spans for each scheduled task. Environment variable: `QUARKUS_SCHEDULER_TRACING_ENABLED` Show more	boolean	`false`
`quarkus.scheduler.use-composite-scheduler` By default, only one `Scheduler` implementation is used. If set to `true` then a composite `Scheduler` that delegates to all running implementations is used. Scheduler implementations will be started depending on the value of `quarkus.scheduler.start-mode`, i.e. the scheduler is not started unless a relevant `io.quarkus.scheduler.Scheduled` business method is found. Environment variable: `QUARKUS_SCHEDULER_USE_COMPOSITE_SCHEDULER` Show more	boolean	`false`
`quarkus.scheduler.enabled` If schedulers are enabled. Environment variable: `QUARKUS_SCHEDULER_ENABLED` Show more	boolean	`true`
`quarkus.scheduler.overdue-grace-period` Scheduled task will be flagged as overdue if next execution time is exceeded by this period. Environment variable: `QUARKUS_SCHEDULER_OVERDUE_GRACE_PERIOD` Show more	Duration	`1S`
`quarkus.scheduler.start-mode` Scheduler can be started in different modes. By default, the scheduler is not started unless a `io.quarkus.scheduler.Scheduled` business method is found. Environment variable: `QUARKUS_SCHEDULER_START_MODE` Show more	`normal`The scheduler is not started unless a `io.quarkus.scheduler.Scheduled` business method is found., `forced`The scheduler will be started even if no scheduled business methods are found. This is necessary for "pure" programmatic scheduling., `halted`Just like the `forced` mode but the scheduler will not start triggering jobs until `Scheduler#resume()` is called. This can be useful to run some initialization logic that needs to be performed before the scheduler starts.	`normal`The scheduler is not started unless a {@link io.quarkus.scheduler.Scheduled} business method is found.

Configuration property

タイプ

デフォルト

quarkus.scheduler.cron-type

The syntax used in CRON expressions.

Environment variable: QUARKUS_SCHEDULER_CRON_TYPE

cron4j, quartz, unix, spring, spring53

quartz

quarkus.scheduler.metrics.enabled

Scheduled task metrics will be enabled if a metrics extension is present and this value is true.

Environment variable: QUARKUS_SCHEDULER_METRICS_ENABLED

boolean

false

quarkus.scheduler.tracing.enabled

Controls whether tracing is enabled. If set to true and the OpenTelemetry extension is present, tracing will be enabled, creating automatic Spans for each scheduled task.

Environment variable: QUARKUS_SCHEDULER_TRACING_ENABLED

boolean

false

quarkus.scheduler.use-composite-scheduler

By default, only one Scheduler implementation is used. If set to true then a composite Scheduler that delegates to all running implementations is used.

Scheduler implementations will be started depending on the value of quarkus.scheduler.start-mode, i.e. the scheduler is not started unless a relevant io.quarkus.scheduler.Scheduled business method is found.

Environment variable: QUARKUS_SCHEDULER_USE_COMPOSITE_SCHEDULER

boolean

false

quarkus.scheduler.enabled

If schedulers are enabled.

Environment variable: QUARKUS_SCHEDULER_ENABLED

boolean

true

quarkus.scheduler.overdue-grace-period

Scheduled task will be flagged as overdue if next execution time is exceeded by this period.

Environment variable: QUARKUS_SCHEDULER_OVERDUE_GRACE_PERIOD

Duration

1S

quarkus.scheduler.start-mode

Scheduler can be started in different modes. By default, the scheduler is not started unless a io.quarkus.scheduler.Scheduled business method is found.

Environment variable: QUARKUS_SCHEDULER_START_MODE

normalThe scheduler is not started unless a io.quarkus.scheduler.Scheduled business method is found., forcedThe scheduler will be started even if no scheduled business methods are found. This is necessary for "pure" programmatic scheduling., haltedJust like the forced mode but the scheduler will not start triggering jobs until Scheduler#resume() is called. This can be useful to run some initialization logic that needs to be performed before the scheduler starts.

normalThe scheduler is not started unless a {@link io.quarkus.scheduler.Scheduled} business method is found.

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

数値のみの場合は、秒単位の時間を表します。
数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。
数値の後に d が続く場合は、その前に P が付けられます。