The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

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

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

Architecture

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.17.2: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.native.enabled=true

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

The syntax used in CRON expressions.

Environment variable: QUARKUS_SCHEDULER_CRON_TYPE

Show more

cron4j, quartz, unix, spring, spring53

quartz

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

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

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

If schedulers are enabled.

Environment variable: QUARKUS_SCHEDULER_ENABLED

Show more

boolean

true

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

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

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

Conteúdo Relacionado