cron-utils

Definiamo i cron. E li supportiamo.

cron-utils è una libreria Java per definire, analizzare, validare e migrare i cron, oltre a ottenere descrizioni leggibili per essi. Il progetto segue la Convenzione sul Versionamento Semantico, fornisce metadati OSGi e utilizza la licenza Apache 2.0.

Download

cron-utils è disponibile sul repository Maven central.

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

Per gli sviluppatori Android, cron-utils 7.0.0 richiede Android 26+. Per versioni Android precedenti considera di usare cron-utils 6.0.6. Se utilizzi ScheduleExpression da Java EE, questa deve essere fornita come dipendenza runtime.

Sviluppo attuale

Attualmente stiamo lavorando per aggiornare il codebase verso JDK 16, per garantire che sia pienamente compatibile con JDK 17 quando verrà rilasciato.

Ora stiamo sviluppando una nuova generazione di cron-descriptors utilizzando la traduzione neurale! Qualsiasi tipo di contributo è benvenuto: dall'aiuto con la generazione di dataset all'addestramento di modelli di machine learning e alle utility per caricarli! Se interessati, seguite l'issue #3

Funzionalità

• Crea espressioni cron arbitrarie: puoi definire il tuo formato cron! I campi supportati sono: secondo, minuto, ora, giorno del mese, mese, giorno della settimana, anno.
• Puoi contrassegnare l'ultimo campo come opzionale!
• Supporta tutti i caratteri speciali di cron: * / , -
  • Sono supportati anche i caratteri non standard L, W, LW, '?' e #!
• Supporta estensioni / soprannomi cron: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly, @reboot
• Stampa in un formato leggibile specifico per locale (cinese, inglese, tedesco, greco, indonesiano, giapponese, coreano, polacco, rumeno, spagnolo, swahili e turco sono completamente supportati. Olandese, francese, italiano, portoghese e russo hanno un supporto di base).
• I processi di parsing e descrizione sono disaccoppiati: fai il parsing una volta e opera con il risultato!
• Costruisci espressioni cron usando CronBuilder:
  • nessun bisogno di ricordare campi e vincoli per ogni provider cron.
  • i cron diventano disaccoppiati dal provider cron: in qualsiasi momento puoi esportarli in un altro formato.
• Verifica se le espressioni cron sono equivalenti.
• Comprimi più espressioni cron in una sola!
• Valida se le espressioni cron in formato stringa corrispondono a una definizione cron.
• Converti i cron tra diverse definizioni cron: se devi migrare espressioni, CronMapper può aiutarti!
• Sono fornite definizioni predefinite per le seguenti librerie cron:
  • Unix
  • Cron4j
  • Quartz
  • Spring. Supportiamo due definizioni: precedenti alla v5.3 e dalla v5.3 in poi.
• Ottieni l'orario dell'ultima/prossima esecuzione e il tempo dall'ultima esecuzione/alla prossima esecuzione.
• Calcola il numero di esecuzioni tra due giorni e confronta i cron in base alle loro frequenze di esecuzione.
• Ottieni il conteggio dei giorni feriali tra due date, considerando diverse politiche di fine settimana e festività.
• Devi mappare costanti tra diverse librerie cron/tempo? Usa ConstantsMapper.

Esempi di utilizzo

Di seguito presentiamo alcuni esempi. Puoi trovare questi e altri in un repository di esempio che abbiamo creato per mostrare le librerie cron-utils!

Costruire definizioni 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);

Costruire un'espressione 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 * ? *

Parsing

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

... anche espressioni multi-cron! Che ne dici di comprimere più cron in un'unica riga? Invece di scrivere 0 0 9 * * ? *, 0 0 10 * * ? *, 0 30 11 * * ? * e 0 0 12 * * ? * possiamo racchiuderle in 0 0|0|30|0 9|10|11|12 * * ? *

Descrizione

// 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 *"));

Migrazione

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

Validazione

cron4jCron.validate()

Calcolare il tempo dall'ultima esecuzione alla prossima

// 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);