cron-utils

Definimos crons. E damos suporte a eles.

cron-utils é uma biblioteca Java para definir, analisar (parse), validar, migrar crons, bem como obter descrições legíveis por humanos para eles. O projeto segue a Convenção de Versionamento Semântico, fornece metadados OSGi e usa licença Apache 2.0.

Download

cron-utils está disponível no repositório Maven central.

<dependency>
    <groupId>com.cronutils</groupId>
    <artifactId>cron-utils</artifactId>
    <version>9.2.1</version>
</dependency>

Para desenvolvedores Android, cron-utils 7.0.0 requer Android 26+. Para versões anteriores do Android, considere usar cron-utils 6.0.6. Se você usa ScheduleExpression do Java EE, ela deve ser fornecida como uma dependência de runtime.

Desenvolvimento atual

Atualmente, estamos trabalhando para atualizar a base de código para o JDK 16, garantindo que será totalmente compatível com o JDK 17 quando for lançado.

Agora estamos desenvolvendo uma nova geração de descritores de cron usando tradução neural! Qualquer tipo de contribuição é bem-vinda: desde ajuda com a geração de datasets até treinamento de modelos de machine learning e utilitários para carregá-los! Se tiver interesse, acompanhe a issue #3

Funcionalidades

• Crie expressões cron arbitrárias: você pode definir seu próprio formato de cron! Os campos suportados são: segundo, minuto, hora, dia do mês, mês, dia da semana, ano.
• Você pode marcar o último campo como opcional!
• Suporta todos os caracteres especiais de cron: * / , -
  • Os caracteres não padronizados L, W, LW, '?' e # também são suportados!
• Suporta extensões / apelidos de cron: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly, @reboot
• Gera descrições legíveis por humanos em formato específico de locale (chinês, inglês, alemão, grego, indonésio, japonês, coreano, polonês, romeno, espanhol, suaíli e turco são totalmente suportados. Holandês, francês, italiano, português e russo têm suporte básico).
• Os processos de parse e descrição são desacoplados: faça o parse uma vez e opere com o resultado!
• Construa expressões cron usando CronBuilder:
  • sem necessidade de lembrar campos e restrições para cada provedor de cron.
  • crons ficam desacoplados do provedor de cron: a qualquer momento você pode exportar para outro formato.
• Verifique se expressões cron são equivalentes.
• Combine múltiplas expressões cron em uma única!
• Valide se expressões de string cron correspondem a uma definição de cron.
• Converta crons entre diferentes definições de cron: se você precisar migrar expressões, CronMapper pode ajudar!
• Definições pré-definidas para as seguintes bibliotecas de cron são fornecidas:
  • Unix
  • Cron4j
  • Quartz
  • Spring. Suportamos duas definições: anteriores à v5.3 e a partir da v5.3.
• Obtenha o horário da última/próxima execução, bem como o tempo desde a última execução/tempo até a próxima execução.
• Calcule o número de execuções entre dois dias e compare crons com base em suas frequências de execução.
• Obtenha a contagem de dias úteis entre duas datas, considerando diferentes políticas de fim de semana e também feriados.
• Precisa mapear constantes entre diferentes bibliotecas de cron/tempo? Use ConstantsMapper.

Exemplos de Uso

Abaixo apresentamos alguns exemplos. Você pode encontrar estes e outros em um repositório de exemplos que criamos para demonstrar as bibliotecas cron-utils!

Construir definições de cron

// Define your own cron: arbitrary fields are allowed and last field can be optional
CronDefinition cronDefinition =
    CronDefinitionBuilder.defineCron()
        .withSeconds().and()
        .withMinutes().and()
        .withHours().and()
        .withDayOfMonth()
            .supportsHash().supportsL().supportsW().and()
        .withMonth().and()
        .withDayOfWeek()
            .withIntMapping(7, 0) //we support non-standard non-zero-based numbers!
            .supportsHash().supportsL().supportsW().and()
        .withYear().optional().and()
        .instance();

// or get a predefined instance
cronDefinition = CronDefinitionBuilder.instanceDefinitionFor(QUARTZ);

Construir uma expressão cron

// Create a cron expression. CronMigrator will ensure you remain cron provider agnostic
import static com.cronutils.model.field.expression.FieldExpressionFactory.*;

Cron cron = CronBuilder.cron(CronDefinitionBuilder.instanceDefinitionFor(CronType.QUARTZ))
    .withYear(always())
    .withDoM(between(SpecialChar.L, 3))
    .withMonth(always())
    .withDoW(questionMark())
    .withHour(always())
    .withMinute(always())
    .withSecond(on(0))
    .instance();
// Obtain the string expression
String cronAsString = cron.asString(); // 0 * * L-3 * ? *

Parse

// Create a parser based on provided definition
CronParser parser = new CronParser(cronDefinition);
Cron quartzCron = parser.parse("0 23 * ? * 1-5 *");

... até mesmo expressões multi-cron! Que tal combinar vários crons em uma única linha? Em vez de escrever 0 0 9 * * ? *, 0 0 10 * * ? *, 0 30 11 * * ? * e 0 0 12 * * ? *, podemos agrupá-los em 0 0|0|30|0 9|10|11|12 * * ? *

Descrever

// Create a descriptor for a specific Locale
CronDescriptor descriptor = CronDescriptor.instance(Locale.UK);

// Parse some expression and ask descriptor for description
String description = descriptor.describe(parser.parse("*/45 * * * * ?"));
// Description will be: "every 45 seconds"

description = descriptor.describe(quartzCron);
// Description will be: "every hour at minute 23 every day between Monday and Friday"
// which is the same description we get for the cron below:
descriptor.describe(parser.parse("0 23 * ? * MON-FRI *"));

Migrar

// Migration between cron libraries has never been so easy!
// Turn cron expressions into another format by using CronMapper:
CronMapper cronMapper = CronMapper.fromQuartzToCron4j();

Cron cron4jCron = cronMapper.map(quartzCron);
// and to get a String representation of it, we can use
cron4jCron.asString();//will return: 23 * * * 1-5

Validar

cron4jCron.validate()

Calcular tempo desde/até a execução

// Get date for last execution
ZonedDateTime now = ZonedDateTime.now();
ExecutionTime executionTime = ExecutionTime.forCron(parser.parse("* * * * * ? *"));
ZonedDateTime lastExecution = executionTime.lastExecution(now);

// Get date for next execution
ZonedDateTime nextExecution = executionTime.nextExecution(now);

// Time from last execution
Duration timeFromLastExecution = executionTime.timeFromLastExecution(now);

// Time to next execution
Duration timeToNextExecution = executionTime.timeToNextExecution(now);