Agendamento Descomplicado com Quarkus Scheduler: Padrões e Boas Práticas

Por que uso do agendamento é importante?

Automação de tarefas recorrentes (limpeza, batch, notificações)

Fonte: Autor

Limpeza de dados: Apagar registros temporários, remover logs antigos e arquivos desnecessários são exemplos frequentes de tarefas de housekeeping em sistemas modernos. Manter o ambiente limpo contribui para melhor performance, libera espaço e reduz riscos de vazamento de informações.

Limpeza periódica simples: Use a anotação “@Scheduled” para agendar tarefas recorrentes de limpeza que sejam rápidas e não exijam persistência de estado entre reinícios da aplicação. Esse padrão é ideal para tarefas leves, como remoção de arquivos temporários, desde que a eventual execução perdida (por exemplo, durante um restart) não comprometa a integridade do sistema.

Processamento em lote (batch): Para tarefas mais intensivas ou que lidam com grandes volumes de dados, considere frameworks como Quartz ou JobRunr, que oferecem maior controle, persistência de estado e tolerância a falhas. Uma abordagem escalável envolve criar microsserviços dedicados exclusivamente ao processamento batch, permitindo segmentação (chunking/paging) dos dados para evitar sobrecarga de memória e possibilitando a execução em horários de menor demanda.

Manutenção: algumas tarefas como automação de limpeza e remoção de sessões expiradas podem facilmente ser automatizadas com métodos anotados com o “@Scheduled”, e utilizá-lo apresenta vantagens como consistência, desempenho e flexibilidade — evita que a base de dados cresça descontroladamente e o intervalo de execução pode ser configurado no application.properties.

Redução de esforço manual e garantia de consistência

Fonte: Autor

Em sistemas modernos, diversas tarefas rotineiras precisam ser executadas de forma periódica — como limpeza de registros temporários, atualização de caches, envio de relatórios ou sincronização de dados entre serviços. Quando essas ações dependem de execução manual, o processo se torna suscetível a falhas.

Processamento em lote (ex: processar filas periodicamente) : Muitos cenários exigem o tratamento periódico de grandes volumes de dados, como o processamento de filas, consolidação de métricas ou geração de relatórios. Ao utilizar padrões de agendamento, essas operações podem ser executadas de forma controlada — por exemplo, durante períodos de menor carga, onde o sistema está sendo menos utilizado — garantindo melhor uso dos recursos e evitando impactos sobre as transações em tempo real.

Utilização no gerenciamento de relatórios: O agendamento permite que os relatórios sejam gerados automaticamente em intervalos regulares e, em ambientes de microsserviços, múltiplos serviços podem precisar gerar relatórios em diferentes horários e com diferentes dados

Configurando o Scheduler no Quarkus

Antes de implementar tarefas agendadas com o Quarkus Scheduler, é necessário configurar corretamente o projeto e incluir as dependências que habilitam o uso do agendador interno da plataforma.

Um projeto Quarkus típico segue uma estrutura simples e organizada:

Fonte: Autor

Essa estrutura segue o padrão Maven e é criada automaticamente ao gerar o projeto com o Quarkus CLI ou via code.quarkus.io.

· Dependências essenciais (pom.xml)

A principal dependência para usar o Scheduler é o módulo quarkus-scheduler. Ela habilita o uso da anotação @Scheduled para execução de tarefas recorrentes.

<dependencies>
    <!-- Core do Quarkus -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-reactive</artifactId>
    </dependency>

    <!-- Extensão de Scheduler -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-scheduler</artifactId>
    </dependency>

    <!-- Logs e métricas são úteis para monitorar jobs -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-logging-json</artifactId>
    </dependency>

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

    <!-- Dependência para testes -->
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-junit5</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

· Configuração mínima no application.properties

#Ativa o agendador (padrão: true)
quarkus.scheduler.enabled=true
#Define timezone padrão para jobs
quarkus.scheduler.timezone=America/Sao_Paulo
#Controla logs detalhados de execução (útil em desenvolvimento)
quarkus.log.category."io.quarkus.scheduler".level=DEBUG

· Exemplo de Job simples

package com.example.scheduler;

import io.quarkus.scheduler.Scheduled;
import jakarta.enterprise.context.ApplicationScoped;
import org.jboss.logging.Logger;

@ApplicationScoped
public class CleanupJob {

    private static final Logger LOG = Logger.getLogger(CleanupJob.class);

    // Executa a cada minuto
    @Scheduled(every="1m")
    void performCleanup() {
        LOG.info("Executando rotina de limpeza de dados temporários...");
        // Lógica de limpeza
    }
}

Padrões Reais de Uso

Nosso usuário trabalha em uma empresa de contabilidade e precisa gerar relatórios financeiros toda sexta-feira para apresentar nas reuniões da segunda. Então, o scheduler trabalharia assim:

// src/main/java/org/example/service/RelatorioFinanceiroScheduler.java
package org.example.service;

import io.quarkus.scheduler.Scheduled;
import jakarta.enterprise.context.ApplicationScoped;
import org.jboss.logging.Logger;

@ApplicationScoped
public class RelatorioFinanceiroScheduler {

    private static final Logger LOG = Logger.getLogger(RelatorioFinanceiroScheduler.class);

    // Este método será executado toda sexta-feira às 18h
    @Scheduled(cron = "0 0 18 ? * FRI")
    void gerarRelatorioSemanal() {
        LOG.info("Iniciando geração automática do relatório financeiro semanal...");

        // Simula a lógica de geração do relatório
        String relatorio = gerarRelatorio();
        enviarRelatorio(relatorio);

        LOG.info("Relatório financeiro semanal gerado e enviado com sucesso.");
    }

    private String gerarRelatorio() {
        // Aqui estaria a lógica real de consulta e montagem dos dados financeiros
        LOG.info("Gerando dados do relatório financeiro...");
        return "Relatório de custos financeiros da semana";
    }

    private void enviarRelatorio(String relatorio) {
        // Aqui poderia ser um envio por email, integração com sistema, etc.
        LOG.info("Enviando relatório: " + relatorio);
    }
}

As vantagens do uso do agendamento nesse processo de geração de relatório incluem:

• Automação: O método anotado com “@Scheduled” é executado automaticamente toda sexta-feira às 18h, sem necessidade de intervenção manual.
• Consistência: Garante que o relatório seja gerado e enviado sempre no mesmo horário, reduzindo riscos de esquecimento.
• Produtividade: Libera o usuário de tarefas repetitivas, permitindo focar em atividades mais estratégicas.
• Flexibilidade: O horário pode ser facilmente ajustado via configuração, se a rotina do escritório mudar.

Usando @Scheduled para jobs cron e intervalados

O código abaixo executa automaticamente uma tarefa todos os dias às 2h da manhã. No caso, “cron 0 0 2 ?” significa:

segundo = 0

minuto = 0

hora = 2

dia = qualquer

mês = qualquer

dia da semana = qualquer

Ou seja, executa a geração do relatório todo dia às 02:00:00.

package com.example.scheduler;

import io.quarkus.scheduler.Scheduled; 
import jakarta.enterprise.context.ApplicationScoped; 
import java.time.LocalDateTime; 
import java.time.format.DateTimeFormatter; 

@ApplicationScoped 
public class RelatorioScheduler { 

// Executa automaticamente todos os dias às 2h da manhã 
@Scheduled(cron = "0 0 2 * * ?") 
void gerarRelatorioDiario() { 
    System.out.println("Iniciando geração automática do relatório diário às " 
                        + LocalDateTime.now()); 
    gerarRelatorio(); 
} 

private void gerarRelatorio() { 
    // Simula geração do relatório 
    try { 
        Thread.sleep(2000); 
        String nomeArquivo = "relatorio_" 
            + LocalDateTime.now()
              .format(DateTimeFormatter.ofPattern("yyyyMMdd")) + ".pdf"; 
        System.out.println(
        "Relatório '"  
        + nomeArquivo + 
        "' gerado com sucesso e salvo em /opt/relatorios/"); 
    } catch (InterruptedException e) { 
        e.printStackTrace(); 
    } 
  } 
}

Intervalos fixos com @Scheduled(every = “…”)

Abaixo é apresentado o mesmo código, porém utilizando @Scheduled(every = “1h”)

import io.quarkus.scheduler.Scheduled;
import jakarta.enterprise.context.ApplicationScoped;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@ApplicationScoped
public class RelatorioScheduler {

    // Executa automaticamente a cada 1 hora
    @Scheduled(every = "1h")
    void gerarRelatorioPeriodico() {
        System.out.println("Iniciando geração automática do relatório às " + LocalDateTime.now());
        gerarRelatorio();
    }

    private void gerarRelatorio() {
        try {
            Thread.sleep(2000);
            String nomeArquivo = "relatorio_" +
                    LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd_HHmm")) +
                    ".pdf";

            System.out.println("Relatório '" + nomeArquivo + "' gerado com sucesso e salvo em /opt/relatorios/");
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
}

Diferente do “cron”, que é utilizado para agendamentos específicos, permitindo configurar dia, mês, hora, minuto, segundo e dia da semana para executar determinada tarefa. “Every” define intervalos fixos, como “a cada 10s” ou “a cada 1h”, sem controle de calendário.

Limitações de uso

Apesar das vantagens do Quarkus Scheduler para automatização de tarefas recorrentes, algumas limitações precisam ser consideradas em cenários de produção.

• Não há, por padrão, suporte a lock distribuído para evitar execuções múltiplas em ambientes clusterizados, nem persistência de estado dos jobs entre reinícios da aplicação.
• Para workflows mais complexos ou necessidades de tolerância a falhas, é melhor aplicado alternativas como Quartz, Airflow ou Kubernetes CronJobs.
• Embora cron e intervalos sejam suportados, intervalos muito curtos ou jobs longos podem não ser bem gerenciados, podendo levar a execuções simultâneas por falta de coordenação.

Conclusão

O Quarkus Scheduler se destaca como uma solução moderna e eficiente para a automação de tarefas periódicas em aplicações Java. Sua integração simples, baseada em anotações intuitivas, permite implementar rotinas de manutenção, processamentos em lote e integrações recorrentes sem a necessidade de dependências externas robustas ou configurações complexas. Ao externalizar parâmetros e centralizar a lógica de agendamento, desenvolvedores podem adaptar facilmente os jobs para diferentes ambientes e necessidades, aumentando a flexibilidade e a manutenibilidade do código.

Além disso, a capacidade de monitoramento por meio de métricas, logs e health checks proporciona maior transparência e confiabilidade operacional. Seguindo boas práticas propostas, como separação de responsabilidades e uso criterioso de configurações, é possível garantir que os jobs agendados rodem de forma segura, previsível e eficiente. Assim, o scheduler representa uma ferramenta valiosa para qualquer aplicação que demande automação de rotinas, independentemente do porte ou complexidade do sistema.

Referências

[embed]Quarkus and Maven Quarkus: Supersonic Subatomic Javaquarkus.io

[embed]Scheduling Periodic Tasks Quarkus: Supersonic Subatomic Javaquarkus.io

[embed]Scheduler Reference Guide Quarkus: Supersonic Subatomic Javapt.quarkus.io