Por Versão

Agendando Tarefas Periódicas

Aplicações modernas geralmente precisam executar tarefas específicas periodicamente. Neste guia, você aprenderá a agendar tarefas periódicas.

Se precisar de um agendador clusterizado, use a extensão Quartz.

Pré-requisitos

Para concluir este guia, você precisa:

Cerca de 15 minutos
Um IDE
JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.9.6
Opcionalmente, o Quarkus CLI se você quiser usá-lo
Opcionalmente, Mandrel ou GraalVM instalado e configurado apropriadamente se você quiser criar um executável nativo (ou Docker se você usar uma compilação de contêiner nativo)

Arquitetura

Neste guia, criamos uma aplicação simples, acessível usando HTTP para obter o valor atual de um contador. Esse contador é incrementado periodicamente (a cada 10 segundos).

Solução

Recomendamos que siga as instruções nas seções seguintes e crie a aplicação passo a passo. No entanto, você pode ir diretamente para o exemplo completo.

Clone o repositório Git: git clone https://github.com/quarkusio/quarkus-quickstarts.git, ou baixe um arquivo.

A solução está localizada no diretório scheduler-quickstart.

Criar o projeto Maven

Primeiro, precisamos de um novo projeto. Crie um novo projeto com o seguinte comando:

CLI

quarkus create app org.acme:scheduler-quickstart \
    --extension='rest,scheduler' \
    --no-code
cd scheduler-quickstart

Para criar um projeto Gradle, adicione a opção --gradle ou --gradle-kotlin-dsl.

Para obter mais informações sobre como instalar e usar a CLI do Quarkus, consulte o guia Quarkus CLI.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.9.5:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=scheduler-quickstart \
    -Dextensions='rest,scheduler' \
    -DnoCode
cd scheduler-quickstart

Para criar um projeto Gradle, adicione a opção '-DbuildTool=gradle' ou '-DbuildTool=gradle-kotlin-dsl'.

Para usuários do Windows:

Se estiver usando cmd, (não use barra invertida '\' e coloque tudo na mesma linha)
Se estiver usando o Powershell, envolva os parâmetros '-D' entre aspas duplas, por exemplo, '"-DprojectArtifactId=scheduler-quickstart"'

Gera um novo projeto que inclui:

uma página acessível em http://localhost:8080
exemplo de arquivos Dockerfile para os modos nativo e jvm
o arquivo de configuração da aplicação

The project also imports the Quarkus REST (formerly RESTEasy Reactive) and scheduler extensions.

Se já tiver o projeto Quarkus configurado, você pode adicionar a extensão scheduler ao projeto executando o seguinte comando no diretório base do projeto:

CLI

quarkus extension add scheduler

Maven

./mvnw quarkus:add-extension -Dextensions='scheduler'

Gradle

./gradlew addExtension --extensions='scheduler'

Isto irá adicionar o seguinte trecho no seu arquivo de build:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-scheduler</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-scheduler")

Criando um trabalho agendado

No pacote org.acme.scheduler, crie a classe CounterBean, com o seguinte conteúdo:

package org.acme.scheduler;

import java.util.concurrent.atomic.AtomicInteger;
import jakarta.enterprise.context.ApplicationScoped;
import io.quarkus.scheduler.Scheduled;
import io.quarkus.scheduler.ScheduledExecution;

@ApplicationScoped              (1)
public class CounterBean {

    private AtomicInteger counter = new AtomicInteger();

    public int get() {  (2)
        return counter.get();
    }

    @Scheduled(every="10s")     (3)
    void increment() {
        counter.incrementAndGet(); (4)
    }

    @Scheduled(cron="0 15 10 * * ?") (5)
    void cronJob(ScheduledExecution execution) {
        counter.incrementAndGet();
        System.out.println(execution.getScheduledFireTime());
    }

    @Scheduled(cron = "{cron.expr}") (6)
    void cronJobWithExpressionInConfig() {
       counter.incrementAndGet();
       System.out.println("Cron expression configured in application.properties");
    }
}

1	Declare o bean no escopo da aplicação
2	O método `get()` permite obter o valor atual.
3	Use a anotação `@Scheduled` para instruir o Quarkus a executar esse método a cada 10 segundos, desde que haja uma thread de trabalho disponível (o Quarkus está usando 10 threads de trabalho para o agendador). Se não estiver disponível, a invocação do método deverá ser reagendada por padrão, ou seja, deverá ser invocada assim que possível. A invocação do método agendado não depende do status ou do resultado da invocação anterior.
4	O código é bastante simples. A cada 10 segundos, o contador é incrementado.
5	Defina um trabalho com uma expressão do tipo cron. O método anotado é executado todos os dias às 10:15 da manhã.
6	Defina um trabalho com uma expressão do tipo cron `cron.expr` que é configurável em `application.properties`.

Atualizando o arquivo de configuração da aplicação

Edite o arquivo application.properties e adicione a configuração cron.expr:

# By default, the syntax used for cron expressions is based on Quartz - https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html
# You can change the syntax using the following property:
# quarkus.scheduler.cron-type=unix
cron.expr=*/5 * * * * ?

Criar o recurso REST

Crie a classe CountResource da seguinte forma:

package org.acme.scheduler;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/count")
public class CountResource {

    @Inject
    CounterBean counter;            (1)


    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "count: " + counter.get();  (2)
    }
}

1	Injete o `CounterBean`
2	Envie de volta o valor atual do contador

Empacote e execute a aplicação

Execute a aplicação com:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

Em outro terminal, execute curl localhost:8080/count para verificar o valor do contador. Após alguns segundos, execute novamente curl localhost:8080/count para verificar se o contador foi incrementado.

Observe o console para verificar se a mensagem Cron expression configured in application.properties foi exibida, indicando que o trabalho cron usando uma expressão configurada em application.properties foi acionado.

Como de costume, a aplicação pode ser empacotada utilizando:

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

E executado com java -jar target/quarkus-app/quarkus-run.jar.

Também é possível gerar o executável nativo com:

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.package.type=native

Referência de Configuração do Agendador

Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.

Configuration property	Tipo	Padrão
`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.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.

Configuration property

Tipo

Padrão

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.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.

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

Você também pode usar um formato simplificado, começando com um número:

Se o valor for apenas um número, ele representará o tempo em segundos.
Se o valor for um número seguido de 'ms', ele representa o tempo em milissegundos.

Em outros casos, o formato simplificado é traduzido para o formato 'java.time.Duration' para análise:

Se o valor for um número seguido de 'h', 'm' ou 's', ele é prefixado com 'PT'.
Se o valor for um número seguido de 'd', ele é prefixado com 'P'.

Pré-requisitos
Arquitetura
Solução
Criar o projeto Maven
Criando um trabalho agendado
Atualizando o arquivo de configuração da aplicação
Criar o recurso REST
Empacote e execute a aplicação
Referência de Configuração do Agendador

Agendando Tarefas Periódicas

Pré-requisitos

Arquitetura

Solução

Criar o projeto Maven

Criando um trabalho agendado

Atualizando o arquivo de configuração da aplicação

Criar o recurso REST

Empacote e execute a aplicação

Referência de Configuração do Agendador

Conteúdo Relacionado

Nas mesmas extensões

Nos mesmos tópicos