我们定义 cron,并支持它们。
cron-utils 是一个 Java 库,用于定义、解析、验证和迁移 cron,以及获取它们的人类可读描述。该项目遵循语义化版本约定,提供 OSGi 元数据,并使用 Apache 2.0 许可证。
下载
cron-utils 可在 Maven 中央仓库 获取。
<dependency>
<groupId>com.cronutils</groupId>
<artifactId>cron-utils</artifactId>
<version>9.2.1</version>
</dependency>
对于 Android 开发者,cron-utils 7.0.0 要求 Android 26 及以上版本。对于更早的 Android 版本,请考虑使用 cron-utils 6.0.6。 如果使用 Java EE 中的 ScheduleExpression,则应将其作为运行时依赖提供。
当前开发
我们目前正在将代码库升级至 JDK 16,以确保在 JDK 17 发布时能完全兼容。
现在我们正在使用神经翻译开发新一代 cron 描述符!欢迎任何形式的贡献:从数据集生成的帮助,到机器学习模型训练以及加载它们的实用工具!如果感兴趣,请关注 issue #3
功能特性
使用示例
下面我们展示一些示例。你可以在我们创建的示例仓库中找到这些及其他示例,该仓库用于展示 cron-utils 库!
构建 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);
构建 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 * ? *
解析
// Create a parser based on provided definition
CronParser parser = new CronParser(cronDefinition);
Cron quartzCron = parser.parse("0 23 * ? * 1-5 *");
... 甚至多 cron 表达式!如何将多个 cron 合并到一行?与其编写 0 0 9 * * ? *、0 0 10 * * ? *、0 30 11 * * ? * 和 0 0 12 * * ? *,我们可以将其包装成 0 0|0|30|0 9|10|11|12 * * ? *
描述
// 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 *"));
迁移
// 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
验证
cron4jCron.validate()
计算距上次/下次执行的时间
// 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 day of week value from Quartz to JodaTime
int jodatimeDayOfWeek =
ConstantsMapper.weekDayMapping(
ConstantsMapper.QUARTZ_WEEK_DAY,
ConstantsMapper.JODATIME_WEEK_DAY
);
人类可读的日期和时间格式化!
使用 htime —— 面向 Java 的人类可读日期时间格式化! 尽管此功能未打包在同一个 jar 中,但它是你可能觉得有用的 cron-utils 项目。
// 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 接口,可直接在控制台中使用 cron-utils,无需编写新项目!CLI 是一个附属项目,可在 cron-utils-cli 获取
用法:java -jar cron-utils.jar com.cronutils.cli.CronUtilsCLI --validate -f [CRON4J|QUARTZ|UNIX] -e '<cron expression>'
示例:java -jar cron-utils.jar com.cronutils.cli.CronUtilsCLI --validate -f UNIX -e '* 1 * * *'
如果你想要一个不需要“cp”的独立 jar,请使用以下命令构建 uber jar:
mvn assembly:assembly -DdescriptorId=jar-with-dependencies
然后,使用以下命令启动 cli-utils(构建在 target 目录中):
java -jar cron-utils-<version>-jar-with-dependencies.jar com.cronutils.cli.CronUtilsCLI --validate -f [CRON4J|QUARTZ|UNIX] -e '<cron expression>'`
贡献与支持!
欢迎贡献!你可以通过以下方式贡献:
查看我们的主页!关于项目的统计数据,你可以访问我们的 OpenHUB 页面。
其他 cron-utils 项目
欢迎访问和使用以下 cron-utils 项目: