Package io.quarkus.scheduler

Annotation Interface Scheduled

@Target(METHOD) @Retention(RUNTIME) @Repeatable(Schedules.class) public @interface Scheduled
Identifies a method of a bean class that is automatically scheduled and invoked by the container.

A scheduled method is a non-abstract non-private method of a bean class. It may be either static or non-static.

The schedule is defined either by cron() or by every() attribute. If both are specified, the cron expression takes precedence. 

 @ApplicationScoped
 class MyService {

     @Scheduled(cron = "0/5 * * * * ?")
     void check() {
         // do something important every 5 seconds
     }
 }
The annotated method must return void, java.util.concurrent.CompletionStage<Void> or io.smallrye.mutiny.Uni<Void> and either declare no parameters or one parameter of type ScheduledExecution.

By default, a scheduled method is executed on the main executor for blocking tasks. However, a scheduled method that returns java.util.concurrent.CompletionStage<Void> or io.smallrye.mutiny.Uni<Void>, or is annotated with NonBlocking is executed on the event loop.

Inheritance of metadata

A subclass never inherits the metadata of a Scheduled method declared on a superclass. For example, suppose the class org.amce.Foo is extended by the class org.amce.Bar. If Foo declares a non-static method annotated with Scheduled then Bar does not inherit the metadata of the scheduled method.
See Also:

  • Field Details

    • DEFAULT_TIMEZONE

      static final String DEFAULT_TIMEZONE
      Constant value for timeZone() indicating that the default timezone should be used.
      See Also:

    • AUTO

      static final String AUTO
      Constant value for executeWith() indicating that the implementation should be selected automatically, i.e. the implementation with highest priority is used.
      See Also:

    • SIMPLE

      static final String SIMPLE
      Constant value for executeWith() indicating that the simple in-memory implementation provided by the quarkus-scheduler extension should be used.

      This implementation has priority 0.

      See Also:

    • QUARTZ

      static final String QUARTZ
      Constant value for executeWith() indicating that the Quartz implementation provided by the quarkus-quartz extension should be used.

      This implementation has priority 1.

      See Also:

  • Element Details

    • identity

      String identity
      Optionally defines a unique identifier for this job.

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(identity = "${myJob.identity}"). Additionally, the property expression can specify a default value: @Scheduled(identity = "${myJob.identity:defaultIdentity}").

      If the value is not provided then a unique id is generated.

      Returns:
      the unique identity of the schedule
      Default:
      ""

    • cron

      String cron
      Defines a cron-like expression. For example "0 15 10 * * ?" fires at 10:15am every day.

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(cron = "${myJob.cronExpression}"). Additionally, the property expression can specify a default value: @Scheduled(cron = "${myJob.cronExpression:0/2 * * * * ?}").

      Furthermore, two special constants can be used to disable the scheduled method: off and disabled. For example, @Scheduled(cron="${myJob.cronExpression:off}") means that if the property is undefined then the method is never executed.

      Returns:
      the cron-like expression
      Default:
      ""

    • every

      String every
      Defines the period between invocations.

      The value is parsed with Duration.parse(CharSequence). However, if an expression starts with a digit and ends with 'd', "P" prefix will be added automatically. If the expression only starts with a digit, "PT" prefix is added automatically, so for example, 15m can be used instead of PT15M and is parsed as "15 minutes". Note that the absolute value of the value is always used.

      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.

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(every = "${myJob.everyExpression}"). Additionally, the property expression can specify a default value: @Scheduled(every = "${myJob.everyExpression:5m}").

      Furthermore, two special constants can be used to disable the scheduled method: off and disabled. For example, @Scheduled(every="${myJob.everyExpression:off}") means that if the property is undefined then the method is never executed.

      Returns:
      the period expression based on the ISO-8601 duration format PnDTnHnMn.nS
      Default:
      ""

    • delay

      long delay
      Delays the time the trigger should start at. The value is rounded to full second.

      By default, the trigger starts when registered.

      Returns:
      the initial delay
      Default:
      0L

    • delayUnit

      TimeUnit delayUnit
      Returns:
      the unit of initial delay
      See Also:
      Default:
      MINUTES

    • delayed

      String delayed
      Defines a period after which the trigger should start. It's an alternative to delay(). If delay() is set to a value greater than zero the value of delayed() is ignored.

      The value is parsed with Duration.parse(CharSequence). However, if an expression starts with a digit and ends with 'd', "P" prefix will be added automatically. If the expression only starts with a digit, "PT" prefix is added automatically, so for example, 15s can be used instead of PT15S and is parsed as "15 seconds". Note that the absolute value of the value is always used.

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(delayed = "${myJob.delayedExpression}"). Additionally, the property expression can specify a default value: @Scheduled(delayed = "${myJob.delayedExpression:5m}").

      Returns:
      the period expression based on the ISO-8601 duration format PnDTnHnMn.nS
      Default:
      ""

    • concurrentExecution

      Scheduled.ConcurrentExecution concurrentExecution
      Specify the strategy to handle concurrent execution of a scheduled method. By default, a scheduled method can be executed concurrently.
      Returns:
      the concurrent execution strategy
      Default:
      PROCEED

    • skipExecutionIf

      Class<? extends Scheduled.SkipPredicate> skipExecutionIf
      Specify the predicate that can be used to skip an execution of a scheduled method.

      The class must either represent a CDI bean or declare a public no-args constructor. In case of CDI, there must be exactly one bean that has the specified class in its set of bean types, otherwise the build fails. Furthermore, the scope of the bean must be active during execution of the job. If the scope is Dependent then the bean instance belongs exclusively to the specific scheduled method and is destroyed when the application is shut down.

      Returns:
      the bean class
      Default:
      io.quarkus.scheduler.Scheduled.Never.class

    • overdueGracePeriod

      String overdueGracePeriod
      Defines a period after which the job is considered overdue.

      The value is parsed with Duration.parse(CharSequence). HHowever, if an expression starts with a digit and ends with 'd', "P" prefix will be added automatically. If the expression only starts with a digit, "PT" prefix is added automatically, so for example, 15m can be used instead of PT15M and is parsed as "15 minutes". Note that the absolute value of the value is always used.

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(overdueGracePeriod = "${myJob.overdueExpression}"). Additionally, the property expression can specify a default value: @Scheduled(overdueGracePeriod = "${myJob.overdueExpression:5m}").

      Returns:
      the period expression based on the ISO-8601 duration format PnDTnHnMn.nS
      Default:
      ""

    • timeZone

      String timeZone
      The time zone ID for the cron().

      The cron expression is evaluated in the context of the default time zone. However, it is also possible to associate the cron expression with a specific time zone. The time zone ID is parsed using ZoneId.of(String).

      The value can be a property expression. In this case, the scheduler attempts to use the configured value instead: @Scheduled(timeZone = "${myJob.timeZone}"). Additionally, the property expression can specify a default value: @Scheduled(timeZone = "${myJob.timeZone:Europe/Prague}").

      The time zone is ignored for interval jobs specified via every().

      Returns:
      the time zone ID
      See Also:
      Default:
      "<<default timezone>>"

    • executeWith

      String executeWith
      Choose a scheduler implementation used to execute a scheduled method.

      Only one scheduler implementation is used for all scheduled methods by default. For example, the quarkus-quartz extension provides an implementation that supports clustering but it also removes the simple in-memory implementation from the game.

      If the quarkus.scheduler.use-composite-scheduler config property is set to true then a composite scheduler is used instead. This means that multiple scheduler implementations are kept running side by side. In this case, it's possible to choose a specific implementation used to execute a scheduled method. By default, the implementation with highest priority is selected automatically.

      If the quarkus.scheduler.use-composite-scheduler config property is set to false (default) and the required implementation is not the implementation with highest priority, then the build fails.

      In any case, if the required implementation is not available, then the build fails.

      Returns:
      the implementation to execute this scheduled method
      See Also:
      Default:
      "<<auto>>"