Quartz教程 第6课 CronTrigger

第6课 CronTrigger

当你需要一个基于日历概念的作业调度器，而不是像SimpleTrigger那样精确指定间隔时间时，CronTrigger比SimpleTrigger更常用。

使用CronTrigger，你可以这样指定触发时间表，例如“每周五的中午”，或是“每周末的上午9:30”，甚至是“一月份每周一、三、五上午9:00到10:00之间每5分钟”。

虽然如此，跟SimpleTrigger一样，CronTrigger也需要指定startTime让调度器生效，指定endTime让调度器终止。

6.1 Cron表达式

Cron表达式用于配置CronTrigger实例。Cron表达式实际上是由7个子表达式组成的字符串，描述了schedule的详细信息。这些子表达式用空格隔开，分别代表：

1. 秒
2. 分
3. 时
4. 月份中的天数
5. 月
6. 星期中的天数
7. 年(可选字段)

一个完整的Cron表达式的字符串例子“0 0 12 ? * WED”，意思是“每周三的上午12:00:00”。

每个子表达式都包含“和”、“或”的两种排列，例如，上一个例子中星期中的天数字段（显示的是“WED”）可以替换为“MON－FRI”，“MON,WED,FRI”，甚至是“MON-WED,SAT”。

通配符（*）可用来表示该字段的任意值，因此*在上面的例子中的月份字段表示“每个月”，*在星期中的天数字段由此明显是表示“一周的任何一天”。

所有这些字段都可以设置一些合法的值。这些值可以是非常明确的，例如对于秒和分来说0-59的数字，对于小时来说0-23的数字。月份中的天数可以是1到31的任意值，但是你需要小心那个月总共有多少天！月份可以指定的值为0到11，或者使用字符串JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV 和 DEC。星期中的天可以指定的值为1到7（1=Sunday），或者使用字符串SUN, MON, TUE, WED, THU, FRI 和 SAT。

“/”字符可用来表示增量的值。例如，如果你在分钟字段写“0/15”，这表示“每次从一小时中的第0分钟开始，每隔15分钟触发”，如果你在分钟字段上写“3/20”，这表示“每次从一小时中的第3分钟开始，每隔20分钟触发”——换句话说，这跟在分钟字段上指定“3，23，43”是一样的。注意细微的区别：“/35”不是表示“每隔35分钟”，而是表示“每次从一小时中的第0分钟开始，每隔35分钟触发”，相当于指定“0，35”。

“?”字符允许出现在月份中的天数和星期中的天数字段中。它一般用来指定“不特定的值”。当你需要其中一个字段中指定不确定的值时，这是非常方便的，这个字符不能用在其它的字段中。可以查看下面的例子（或是CronTrigger的JavaDoc）对它的说明。

“L”字符允许出现在月份中的天数和星期中的天数字段中。这个字符是“last”的缩写，但是在这两个字段中有不同的含义。例如，“L”字符出现在月份中的天数字段中表示“每月的最后一天”——1月31日，平年的2月28日。如果该字符单独用在星期中的天数字段时，仅仅是表示“7”或是“SAT”。但是在星期中的天数字段中该字符用在其它值的后面，表示“每月的最后一个星期几”——例如“6L”或是“FRIL”都表示“每月的最后一个星期五”。你也可以指定每月最后一天的偏移数，例如“L－3”表示日历月份的最后三天。当你使用“L”字符时，最好不要使用多个值或是带范围的值，否则你会对结果感到意外和难以理解。

“W”字符用来指定给定日期的最近一个工作日（工作日指的是从周一到周五）。例如，如果你在月份中的天数字段的值指定为“15W”，这表示“离每月15号最近的工作日”。

“#”字符用来指定每月的第N个工作日，例如，星期中的天数字段的值为“6#3”或是“FRI#3”表示“每月的第三个星期五”。

下面演示了一些Cron表达式的例子和它们的含义。你可以在org.quartz.CronExpression或者JavaDoc中找到更多信息。

6.2 Cron表达式示例

CronTrigger示例1 - 创建一个trigger的表达式，每5分钟触发一次：

“0 0/5 * * * ?”

CronTrigger示例2 - 创建一个trigger的表达式，每5分钟触发一次，在每分钟的10秒之后(即10:00:10 am, 10:05:10 am等等)：

“10 0/5 * * * ?”

CronTrigger示例3 - 创建一个trigger的表达式，每周三和周五的10:30、11:30、12:30和13:30触发：

“0 30 10-13 ? * WED,FRI”

CronTrigger示例4 - 创建一个trigger的表达式，在每一个月的第5天和第20天的上午8点到上午10点之间的每半小时触发一次。注意，在上午10:00不会触发，只会在8:00、8:30、9:00、9:30触发：

“0 0/30 8-9 5,20 * ?”

注意，有一些调度需求用单个trigger表达太复杂：例如“上午9:00到上午10:00之间的每5分钟，下午1:00到下午10:00的每20分钟”。这个场景的解决方案是简单的场景两个trigger，将它们注册到相同的job里。

6.3 构建CronTrigger

CronTrigger实例是由TriggerBuilder(用于设置trigger的主要属性)和CronScheduleBuilder(用于设置CronTrigger特定的属性)构建的。以DSL风格使用这些构建器，可使用静态导入：

import static org.quartz.TriggerBuilder.*;

import static org.quartz.CronScheduleBuilder.*;

import static org.quartz.DateBuilder.*:

1、构建一个trigger，每天的从上午8点到下午5点，每两分钟触发一次：

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(cronSchedule("0 0/2 8-17 * * ?"))

    .forJob("myJob", "group1")

    .build();

2、构建一个trigger，每天上午10:42触发：

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(dailyAtHourAndMinute(10, 42))

    .forJob(myJobKey)

    .build();

或者

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(cronSchedule("0 42 10 * * ?"))

    .forJob(myJobKey)

    .build();

3、构建一个trigger，在周三上午10:42（指定时区TimeZone，而不是系统默认时区）触发：

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(weeklyOnDayAndHourAndMinute(DateBuilder.WEDNESDAY, 10, 42))

    .forJob(myJobKey)

    .inTimeZone(TimeZone.getTimeZone("America/Los_Angeles"))

    .build();

或者

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(cronSchedule("0 42 10 ? * WED"))

    .inTimeZone(TimeZone.getTimeZone("America/Los_Angeles"))

    .forJob(myJobKey)

    .build();

6.4 CronTrigger失败指令

下面几条指令用来告知Quartz当CronTrigger触发失败时，它应该怎么做。(在本教程的第4课 Trigger详解已经介绍过失败机制)。CronTrigger自己将指令定义成了常量(包含描述它们行为的JavaDoc)。这些指令包括：

CronTrigger失败指令常量

MISFIRE_INSTRUCTION_IGNORE_MISFIRE_POLICY

MISFIRE_INSTRUCTION_DO_NOTHING

MISFIRE_INSTRUCTION_FIRE_NOW

所有的触发器都可以使用Trigger.MISFIRE_INSTRUCTION_SMART_POLICY指令，并且这条指令也是所有触发器的默认指令。CronTrigger将“智能策略”指令解释为MISFIRE_INSTRUCTION_FIRE_NOW。CronTrigger.updateAfterMisfire()方法的JavaDoc对这个行为进行了详细解释。

当你创建CronTrigger时，可以通过CronSchedulerBuilder指定触发失败指令：

  trigger = newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(cronSchedule("0 0/2 8-17 * * ?")

        .withMisfireHandlingInstructionFireAndProceed())

    .forJob("myJob", "group1")

    .build();