search

jmrozanec / cron-utils

Cron utils for parsing, validations and human readable descriptions as well as date/time interoperability.
http://cron-utils.com
Apache License 2.0
1.15k stars 262 forks source link
cron cron-definitions cron-expression cron-libraries cron-utils cron4j crontab hacktoberfest java quartz

readme

cron-utils

We define crons. And support them.

cron-utils is a Java library to define, parse, validate, migrate crons as well as get human readable descriptions for them. The project follows the Semantic Versioning Convention, provides OSGi metadata and uses Apache 2.0 license.

Gitter Chat Build Status Quality Gate

Download

cron-utils is available on Maven central repository.

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

For Android developers, cron-utils 7.0.0 assumes Android 26+. For earlier Android versions consider using cron-utils 6.0.6. If using ScheduleExpression from Java EE, this should be provided as a runtime dependency.

Current development

We are currently working to update the codebase towards JDK 16, to ensure will be fully compatible with JDK 17 when released.

Now we are developing a new generation of cron-descriptors using neural-translation! Any kind of contributions are welcome: from help with dataset generation to machine learning models training and utilities to load them! If interested, please follow issue #3

Features

Usage Examples

Below we present some examples. You can find this and others in a sample repo we created to showcase cron-utils libraries!

Build cron definitions

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

Build a cron expression

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

... even multi-cron expressions! How about squashing multiple crons into a single line? Instead of writing 0 0 9 * * ? *, 0 0 10 * * ? *, 0 30 11 * * ? * and 0 0 12 * * ? * we can wrap it into 0 0|0|30|0 9|10|11|12 * * ? *

Describe

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

Migrate

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

Validate

cron4jCron.validate()

Calculate time from/to execution

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

Map constants between libraries

// Map day of week value from Quartz to JodaTime
int jodatimeDayOfWeek =
        ConstantsMapper.weekDayMapping(
                ConstantsMapper.QUARTZ_WEEK_DAY,
                ConstantsMapper.JODATIME_WEEK_DAY
        );

Date and time formatting for humans!

Use htime - Human readable datetime formatting for Java! Despite this functionality is not bundled in the same jar, is a cron-utils project you may find useful.

// You no longer need to remember "YYYY-MM-dd KK a" patterns.
DateTimeFormatter formatter = 
        HDateTimeFormatBuilder
            .getInstance()
            .forJodaTime()
            .getFormatter(Locale.US)
            .forPattern("June 9, 2011");
String formattedDateTime = formatter.print(lastExecution);
// formattedDateTime will be lastExecution in "dayOfWeek, Month day, Year" format

cron-utils CLI

We provide a simple CLI interface to use cron-utils right from console, without writing a new project! The CLI is a satellite project, available at cron-utils-cli

If you want a standalone jar without requiring the 'cp', build an uber jar with :

mvn assembly:assembly -DdescriptorId=jar-with-dependencies

Then, launch cli-utils (built in the target directory) with :

java -jar cron-utils-<version>-jar-with-dependencies.jar com.cronutils.cli.CronUtilsCLI --validate -f [CRON4J|QUARTZ|UNIX] -e '<cron expression>'`

Contribute & Support!

Contributions are welcome! You can contribute by

Check our page! For stats about the project, you can visit our OpenHUB profile.

Other cron-utils projects

You are welcome to visit and use the following cron-utils projects: