{"id":15029619,"url":"https://github.com/jmrozanec/cron-utils","last_synced_at":"2025-04-29T14:32:03.912Z","repository":{"id":19499079,"uuid":"22745381","full_name":"jmrozanec/cron-utils","owner":"jmrozanec","description":"Cron utils for parsing, validations and human readable descriptions as well as date/time interoperability.","archived":false,"fork":false,"pushed_at":"2024-07-23T08:48:20.000Z","size":2567,"stargazers_count":1173,"open_issues_count":50,"forks_count":267,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-09T01:22:32.421Z","etag":null,"topics":["cron","cron-definitions","cron-expression","cron-libraries","cron-utils","cron4j","crontab","hacktoberfest","java","quartz"],"latest_commit_sha":null,"homepage":"http://cron-utils.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmrozanec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-08T03:55:20.000Z","updated_at":"2025-04-07T07:31:46.000Z","dependencies_parsed_at":"2024-05-02T07:53:06.642Z","dependency_job_id":"9e7451e1-a7f0-44de-839e-f3e8eada681b","html_url":"https://github.com/jmrozanec/cron-utils","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrozanec%2Fcron-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrozanec%2Fcron-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrozanec%2Fcron-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmrozanec%2Fcron-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmrozanec","download_url":"https://codeload.github.com/jmrozanec/cron-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251519024,"owners_count":21602253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron","cron-definitions","cron-expression","cron-libraries","cron-utils","cron4j","crontab","hacktoberfest","java","quartz"],"created_at":"2024-09-24T20:11:12.507Z","updated_at":"2025-04-29T14:32:03.890Z","avatar_url":"https://github.com/jmrozanec.png","language":"Java","readme":"# cron-utils\n_We define crons. And support them._\n\n\ncron-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](http://semver.org/), provides OSGi metadata and uses Apache 2.0 license.\n\n[![Gitter Chat](http://img.shields.io/badge/chat-online-brightgreen.svg)](https://gitter.im/jmrozanec/cron-utils)\n[![Build Status](https://travis-ci.org/jmrozanec/cron-utils.png?branch=master)](https://travis-ci.org/jmrozanec/cron-utils)\n[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=cron-utils\u0026metric=coverage)](https://sonarcloud.io/dashboard/index/cron-utils)\n\n\n**Download**\n\ncron-utils is available on [Maven central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.cronutils%22) repository.\n\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.cronutils\u003c/groupId\u003e\n        \u003cartifactId\u003ecron-utils\u003c/artifactId\u003e\n        \u003cversion\u003e9.2.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\nFor Android developers, cron-utils 7.0.0 assumes Android 26+. For earlier Android versions consider using cron-utils 6.0.6.\nIf using ScheduleExpression from Java EE, this should be provided as a runtime dependency.\n\n**Current development**\n\n*We are currently working to update the codebase towards JDK 16, to ensure will be fully compatible with JDK 17 when released.* \n\nNow 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](https://github.com/jmrozanec/cron-utils/issues/3)\n\n**Features**\n\n * Create arbitrary cron expressions: you can define your own cron format! Supported fields are: second, minute, hour, day of month, month, day of week, year.\n * You can flag last field as optional!\n * Supports all cron special characters: * / , -\n    * Non-standard characters L, W, LW, '?' and # are supported as well!\n * Supports cron extensions / nicknames: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly, @reboot\n * Print to locale specific human readable format (Chinese, English, German, Greek, Indonesian, Japanese, Korean, Polish, Romanian, Spanish, Swahili, and Turkish are fully supported. Dutch, French, Italian, Portuguese and Russian have basic support).\n * Parse and Description process are decoupled: parse once and operate with the result!\n * Build cron expressions using CronBuilder: \n    * no need to remember fields and constraints for each cron provider.\n    * crons become decoupled from cron provider: anytime you can export to another format.\n * Check if cron expressions are equivalent.\n * Squash multiple cron expressions into a single one!\n * Validate if cron string expressions match a cron definition.\n * Convert crons between different cron definitions: if you need to migrate expressions, CronMapper may help you!\n * Pre-defined definitions for the following cron libraries are provided:\n    * [Unix](http://www.unix.com/man-page/linux/5/crontab/)\n    * [Cron4j](http://www.sauronsoftware.it/projects/cron4j/)\n    * [Quartz](http://quartz-scheduler.org/)\n    * [Spring](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/support/CronExpression.html). We support two definitions: prior to v5.3 and [from v5.3 onwards](https://spring.io/blog/2020/11/10/new-in-spring-5-3-improved-cron-expressions).\n * Obtain last/next execution time as well as time from last execution/time to next execution.\n * Compute the number of executions between two days, and compare crons based on their execution frequencies.\n * Obtain weekdays count between two dates, considering different weekend policies as well as holidays.\n * Need to map constants between different cron/time libraries? Use ConstantsMapper.\n\n**Usage Examples**\n\nBelow we present some examples. You can find this and others in a [sample repo we created](https://github.com/jmrozanec/cron-utils-examples) to showcase cron-utils libraries!\n\n***Build cron definitions***\n\n```java\n// Define your own cron: arbitrary fields are allowed and last field can be optional\nCronDefinition cronDefinition =\n    CronDefinitionBuilder.defineCron()\n        .withSeconds().and()\n        .withMinutes().and()\n        .withHours().and()\n        .withDayOfMonth()\n            .supportsHash().supportsL().supportsW().and()\n        .withMonth().and()\n        .withDayOfWeek()\n            .withIntMapping(7, 0) //we support non-standard non-zero-based numbers!\n            .supportsHash().supportsL().supportsW().and()\n        .withYear().optional().and()\n        .instance();\n\n// or get a predefined instance\ncronDefinition = CronDefinitionBuilder.instanceDefinitionFor(QUARTZ);\n```\n\n***Build a cron expression***\n```java \n// Create a cron expression. CronMigrator will ensure you remain cron provider agnostic\nimport static com.cronutils.model.field.expression.FieldExpressionFactory.*;\n\nCron cron = CronBuilder.cron(CronDefinitionBuilder.instanceDefinitionFor(CronType.QUARTZ))\n    .withYear(always())\n    .withDoM(between(SpecialChar.L, 3))\n    .withMonth(always())\n    .withDoW(questionMark())\n    .withHour(always())\n    .withMinute(always())\n    .withSecond(on(0))\n    .instance();\n// Obtain the string expression\nString cronAsString = cron.asString(); // 0 * * L-3 * ? *\n```\n\n***Parse***\n```java\n// Create a parser based on provided definition\nCronParser parser = new CronParser(cronDefinition);\nCron quartzCron = parser.parse(\"0 23 * ? * 1-5 *\");\n```\n\n... 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 * * ? *```\n\n\n***Describe***\n```java\n// Create a descriptor for a specific Locale\nCronDescriptor descriptor = CronDescriptor.instance(Locale.UK);\n\n// Parse some expression and ask descriptor for description\nString description = descriptor.describe(parser.parse(\"*/45 * * * * ?\"));\n// Description will be: \"every 45 seconds\"\n\ndescription = descriptor.describe(quartzCron);\n// Description will be: \"every hour at minute 23 every day between Monday and Friday\"\n// which is the same description we get for the cron below:\ndescriptor.describe(parser.parse(\"0 23 * ? * MON-FRI *\"));\n```\n\n***Migrate***\n```java\n// Migration between cron libraries has never been so easy!\n// Turn cron expressions into another format by using CronMapper:\nCronMapper cronMapper = CronMapper.fromQuartzToCron4j();\n\nCron cron4jCron = cronMapper.map(quartzCron);\n// and to get a String representation of it, we can use\ncron4jCron.asString();//will return: 23 * * * 1-5\n```\n\n***Validate***\n```java\ncron4jCron.validate()\n```\n\n***Calculate time from/to execution***\n```java\n// Get date for last execution\nZonedDateTime now = ZonedDateTime.now();\nExecutionTime executionTime = ExecutionTime.forCron(parser.parse(\"* * * * * ? *\"));\nZonedDateTime lastExecution = executionTime.lastExecution(now);\n\n// Get date for next execution\nZonedDateTime nextExecution = executionTime.nextExecution(now);\n\n// Time from last execution\nDuration timeFromLastExecution = executionTime.timeFromLastExecution(now);\n\n// Time to next execution\nDuration timeToNextExecution = executionTime.timeToNextExecution(now);\n```\n\n***Map constants between libraries***\n```java\n// Map day of week value from Quartz to JodaTime\nint jodatimeDayOfWeek =\n        ConstantsMapper.weekDayMapping(\n                ConstantsMapper.QUARTZ_WEEK_DAY,\n                ConstantsMapper.JODATIME_WEEK_DAY\n        );\n```\n***Date and time formatting for humans!***\n\nUse [htime](https://github.com/jmrozanec/htime) - Human readable datetime formatting for Java!\nDespite this functionality is not bundled in the same jar, is a cron-utils project you may find useful.\n```java\n// You no longer need to remember \"YYYY-MM-dd KK a\" patterns.\nDateTimeFormatter formatter = \n\t    HDateTimeFormatBuilder\n\t\t    .getInstance()\n\t\t    .forJodaTime()\n\t\t    .getFormatter(Locale.US)\n\t\t    .forPattern(\"June 9, 2011\");\nString formattedDateTime = formatter.print(lastExecution);\n// formattedDateTime will be lastExecution in \"dayOfWeek, Month day, Year\" format\n```\n\n***cron-utils CLI***\n\nWe 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](https://github.com/jmrozanec/cron-utils-cli)\n\n- Usage: `java -jar cron-utils.jar com.cronutils.cli.CronUtilsCLI --validate -f [CRON4J|QUARTZ|UNIX] -e '\u003ccron expression\u003e'`\n\n- Example: `java -jar cron-utils.jar com.cronutils.cli.CronUtilsCLI --validate -f UNIX -e '* 1 * * *'`\n\nIf you want a standalone jar without requiring the 'cp', build an uber jar with :\n```bash\nmvn assembly:assembly -DdescriptorId=jar-with-dependencies\n```\nThen, launch cli-utils (built in the `target` directory) with :\n```bash\njava -jar cron-utils-\u003cversion\u003e-jar-with-dependencies.jar com.cronutils.cli.CronUtilsCLI --validate -f [CRON4J|QUARTZ|UNIX] -e '\u003ccron expression\u003e'`\n```\n\n**Contribute \u0026 Support!**\n\nContributions are welcome! You can contribute by\n * starring this repo!\n * requesting or adding new features. Check our [roadmap](https://github.com/jmrozanec/cron-utils/wiki/Roadmap)!\n * enhancing existing code: ex.: provide more accurate description cases\n * testing\n * enhancing documentation\n * providing translations to support new locales\n * bringing suggestions and reporting bugs\n * spreading the word \n * telling us how you use it! We look forward to [list you at our wiki](https://github.com/jmrozanec/cron-utils/wiki/Projects-using-cron-utils)!\n\n\nCheck [our page](http://cronutils.com)! For stats about the project, you can visit our [OpenHUB profile](https://www.openhub.net/p/cron-utils).\n\n**Other cron-utils projects**\n\nYou are welcome to visit and use the following cron-utils projects:\n * [htime](https://github.com/jmrozanec/htime): A Java library to make it easy for humans format a date. You no longer need to remember date time formatting chars: just write an example, and you will get the appropriate formatter.\n * [cron-utils-spring](https://github.com/jmrozanec/cron-utils-spring): A Java library to describe cron expressions in human readable language at Spring framework, using cron-utils.\n * [cron-utils-cli](https://github.com/jmrozanec/cron-utils-cli): cron-utils features made available through a CLI.\n * [cron-utils-sisyphus](https://github.com/jmrozanec/cron-utils-sisyphus): A Scala scheduler that supports multiple cron notations.\n * [cron-utils-scheduler](https://github.com/jmrozanec/cron-utils-scheduler): A Java job scheduler based on cron-utils library.\n","funding_links":[],"categories":["Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmrozanec%2Fcron-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmrozanec%2Fcron-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmrozanec%2Fcron-utils/lists"}