1 Overview
Quartz是一个开源的作业调度框架,可被集成到任何的Java EE 或者Java SE程序中。
2 Scheduler
通过SchedulerFactory接口创建Scheduler对象。当 Scheduler 实例被创建之后,就会被保存到一个仓库中(org.quartz.impl.SchedulerRepository)。Scheduler对象可以被start、standby和shutdown。一旦Scheduler被shutdown,那么不应该重新启动它。Scheduler对象被启动后,Triggers才会被触发。在Trigger被触发时,Scheduler会创建 Job 类的实例,执行实例的 execute() 方法并传入JobExecutionContext 上下文变量,JobExecutionContext封装了 Quartz 的运行时环境。
2.1 StdScheduler
可以通过调用以java.util.Properties为参数的initialize方法对StdSchedulerFactory实例进行配置。StdSchedulerFactory 还提供了一个静态方法 getDefaultScheduler()用来获得默认的Scheduler,假如之前未调用过任何一个 initialize() 方法,那么无参的 initialize() 方法会被调用。如果使用无参的 initialize 方法,StdSchedulerFactory 会执行以下几个步骤去尝试为工厂加载属性:
1. 检查System.getProperty("org.quartz.properties") 中是否设置了别的文件名;否则使用 quartz.properties 作为要加载的文件名。
2. 试图从当前工作目录中加载这个文件。
3. 试图从系统 classpath 下加载这个文件。这一步总是能成功的,因为在 Quartz Jar 包中有一个默认的 quartz.properties 文件。
以下是个quartz.properties 文件的例子:
org.quartz.scheduler.instanceName用于指定Scheduler的实例名,可以是任意字符串。org.quartz.scheduler.instanceId用于指定实例ID,也可以是任意字符串。在集群环境中instanceId必须唯一。如果希望 Quartz 自动生成这个值,那么可以设置为 AUTO。如果 Quartz 框架是运行在非集群环境中,那么自动产生的值将会是 NON_CLUSTERED;如果是在集群环境下使用 Quartz,这个值将会是主机名加上当前的日期和时间。
org.quartz.threadPool.class属性值是一个实现了 org.quartz.spi.ThreadPool 接口的全限定类名。Quartz 自带的实现类是 org.quartz.smpl.SimpleThreadPool,它提供了固定大小的线程池,并经很好的测试过,能满足绝大多数情况下的需求。你也可以指定其它的线程池实现,例如需要一个可伸缩的线程池。
org.quartz.jobStore.class属性指定了在Scheduler的生命周期中,Job 和 Trigger 信息是如何被存储的。如果使用RAMJobStore,那么一旦调度器进程被终止,所有的 Job 和 Trigger 的状态就丢失了。除了RAMJobStore,还可以指定JDBCJobStore。虽然JDBCJobStore的性能不如RAMJobStore,但是可以持久地保存Job 和 Trigger 信息。
以下是个简单的例子:
3 Job
一个 Quartz Job 就是一个执行任务的 Java 类。Job 的实例要到该执行它们的时候才会实例化出来。这意味着 Job 不必担心线程安全性,因为同一时刻仅有一个线程去执行给定 Job 类的实例。Job有以下三个主要的属性:
易失性(volatility)。Job在程序关闭之后是否被持久化。 通过调用 JobDetail 的 setVolatility(boolean flag) 进行设置,默认值是 false。RamJobStore 使用的是非永久性存储器,所有关于 Job 和 Trigger 的信息会在程序关闭之后丢失。保存 Job 到 RamJobStore使得它们是易失性的。假如你需要让你的 Job 信息在程序重启之后仍能保留下来,你就该使用JDBCJobStore。
持久性(Durability)。 在所有的触发器触发之后,是否将Job从 JobStore 中移除。通过调用 JobDetail 的 setDurability(boolean flag) 方法设置,默认值是 false。假设设置了一个单次触发的 Trigger,触发之后它就变成了 STATE_COMPLETE 状态。这个 Trigger 指向的 Job 现在成了一个孤儿 Job,因为不再有任何 Trigger 与之相关联了。假如你设置这个Job为持久的,那么即使它成了孤儿 Job 也不会从 JobStore 移除掉。这样可以保证在将来,无论何时你的程序决定为这个 Job 增加另一个 Trigger 都是可用的。
可恢复性(Recovery)。当一个 Job 还在执行中,Scheduler 经历了一次非预期的关闭,在 Scheduler 重启之后该 Job 是否会重头开始再次被执行。通过调用 JobDetail 的 setRequestsRecovery(boolean flag)方法设置,默认值是 false。
3.1 JobDetail
实际上,并不是直接把 Job 对象注册到 Scheduler,而是注册一个 JobDetail 实例。JobDetail用于对Job进行配置。每当Trigger被触发时,Scheduler会创建相对应的Job的实例并调用其execute方法。传入的JobExecutionContext参数包含了该Job的运行时环境,例如得到相关的Scheduler、Trigger和JobDetail。
3.2 JobDataMap
由于每次调度Job的时候都有一个新的Job实例被创建,因此每次Job被调度后状态都丢失了。通过使用JobDataMap,可以向Job传递配置信息,或者保存多次调度之间的作业状态。JobDataMap 通过它的超类 org.quartz.util.DirtyFlagMap 实现了java.util.Map 接口。如果你使用的是持久化的JobStore(例如JDBCJobStore),那么JobDataMap中存放的数据必须能够被序列化。
可以在JobDetail和Trigger上设置JobDataMap。如果向 JobDataMap 中存入键/值对,那么这些数据可以在Job实例被执行时,通过传入参数JobExecutionContext中包含的Trigger和JobDetail实例访问到,因此这是一个向 Job实例传送配置的信息便捷方法。JobExecutionContext提供了一个方法getMergedJobDataMap,用于得到JobDetail和Trigger中包含的JobDataMap的合并后版本。需要注意的是,如果键/值对冲突,那么Trigger中包含的JobDataMap的值会覆盖掉JobDetail中包含的JobDataMap的值。以下是个简单的例子:
3.3 Job
Job定义如下:
每当Scheduler调度Job的时候,Scheduler根据配置的JobFactory创建一个新的Job实例。默认的JobFactory(org.quartz.simpl.SimpleJobFactory)只是通过反射,即调用Job类的newInstance方法构造Job实例,因此Job类需要有个可访问的无参构造函数。
3.4 StatefulJob
StatefulJob扩展Job,没有添加新的方法,其定义如下:
当你需要在两次 Job 执行间维护状态的话,Quartz 框架为此提供了 org.quartz.StatefulJob 接口。Job 和 StatefulJob 存在以下两个关键差异:
JobDataMap 在每次执行之后重新持久化到 JobStore 中。这样就确保对stateful Job执行时对JobDataMap的修改都会保存,下次执行时也仍然可见。对于non-stateful Job,JobDataMap只是在JobDetail被注册到Scheduler的时候持久化到JobStore 中,这意味着每次non-stateful Job执行时对JobDataMap的修改都会被丢弃。
两个或多个有状态的 JobDetail 实例不能并发执行。如果有两个Trigger试图同时触发一个相同的stateful Job,那么其中一个Trigger会被阻塞,直到另外一个Trigger触发的Job执行完毕。这确保了不会对JobDataMap进行并发的修改,从而确保了线程安全。
下面是个使用StatefulJob接口的例子:
以上程序的输出如下:
3.5 InterruptableJob
InterruptableJob扩展Job,其定义如下:
可以通过调用Scheduler 接口的interrupt(String jobName, String groupName) 方法来中断特定的Job。Scheduler会负责调用InterruptableJob的interrupt()方法。至于Job如何被中断,这要取决于Job的具体实现。下面是个使用InterruptableJob接口的例子:
以上程序的输出如下:
需要注意的是,以上例子中构造JobDetail的第二个参数group为null(即使用默认的group),因此在调用Scheduler的interrupt()方法时的第二个参数(group)也必须为null。
4 Trigger
Job 包含了要执行任务的逻辑,Trigger 决定了Job 何时被执行。可以为单个Job 使用多个 Trigger,但一个 Trigger 只能被指派给一个 Job。Trigger上也可以配置JobDataMap,当Trigger触发时,被执行的Job实例可以获得Trigger所关联的JobDataMap。特别是当多个Trigger被关联到一个JobDetail时,可以通过Trigger所关联的JobDataMap向Job提供额外的配置信息。Quartz提供了多种Trigger实现,最常用的有SimpleTrigger、NthIncludeDayTrigger和CronTrigger。
某一时刻,假设有m个trigger可能被触发,但是只有n(m > n)个工作线程可用,那么具有最高优先级的n个trigger会优先被触发。通过Trigger的setPriority(int priority)方法可以调整Trigger的优先级,默认优先级是5。
Trigger的另外一个比较重要的属性是misfire instruction。由于scheduler被shutdown,trigger被pause或者没有可用的工作线程等原因,都会导致trigger没有被触发。不同类型的Trigger可以设置不同的misfire instruction。
4.1 SimpleTrigger
SimpleTrigger是最简单的一种 Trigger。 如果你需要某个Job在特定时间执行一次,或者在某个时间执行一次后再以特定的间隔重复执行 n 次,那么可以使用SimpleTrigger。SimpleTrigger包含以下属性:开始时间、结束时间、重复次数和重复间隔。重复次数可以是0、正整数或者SimpleTrigger.REPEAT_INDEFINITELY。重复间隔的单位是毫秒。如果设置了结束时间,那么它会覆盖重复次数,例如你设置了开始时间、结束时间和重复间隔,那么Quartz会自动计算重复次数。下面是个使用SimpleTrigger的例子:
以上程序的输出如下:
如果将以上例子中props的org.quartz.threadPool.threadCount属性设置为2(也就是说最多同时能执行2个Job),那么程序的输出如下:
从以上输出可以看出,本应该在09:31:12左右调度的第三个任务,由于没有可用的线程而被阻塞,直到第一个任务结束之后(09:31:13)才被调度。需要注意的是,如果给trigger设置不同的misfire instruction,可能会有不同的行为。
4.2 NthIncludeDayTrigger
NthIncludedDayTrigger用于在每一间隔类型的第几天执行 Job,例如要在每个月的 15 号执行特定的 Job。目前Quartz 支持的间隔类型有:INTERVAL_TYPE_WEEKLY、INTERVAL_TYPE_MONTHLY和INTERVAL_TYPE_YEARLY。下面是个使用NthIncludeDayTrigger的例子:
以上例子中,任务被配置成在每月15日执行。执行时间可以通过NthIncludedDayTrigger的setFireAtTime(String fireAtTime)方法设置,默认是12:00:00。
4.3 CronTrigger
SimpleTrigger 对于需要在指定的时间(毫秒级)执行的Job还是不错的,但是假如你的Job需要更复杂的执行计划时,可能需要使用CronTrigger 提供的更灵活的功能。
CronExpression用于配置CronTrigger,它封装了一个字符串,这个字符串由空格分割的7个子表达式构成,它们分别代表:
例如"0 0 12 ? * WED"代表每周三的12点,"* * * ? * *"则代表每秒都执行。每个子表达式都有可选值的集合:Seconds和Minutes的可选值是0到59;Hours的可选值是0到23;Day-of-Month的可选值是1到31;Months的可选值是0到11,或者使用JAN、FEB、MAR、APR、MAY、JUN、JUL、AUG、SEP、OCT、NOV和DEC;Days-of-Week的可选值是1到7(1代表周日),或者是SUN、MON、TUE、WED、THU、FRI和SAT。每个子表达式也可以包含范围和列表。例如"MON-FRI"代表一个范围,即周一到周五;"MON, WED, FRI"代表一个列表,即周一、周三和周五;"MON-WED,SAT"代表周一、周二、周三和周六。
CronExpression表达式支持用特殊字符来创建更为复杂的执行计划。下面是可以在CronExpression中使用的特殊字符:
通配符"*"代表每一个可能的值。
"/"用于指定值的增量,例如Minutes字段上的"0/15"代表从0分钟起每隔15分钟。
"?"可以放在Day-of-Month和Day-of-Week中。"?"表示这个字段不包含具体值。所以如果指定Day-of-Month,那么可以在Day-of-Week字段中设置"?",表示Day-of-Week值无关紧要。
"L"可以放在Day-of-Month和Day-of-Week中。Day-of-Month表示在当月最后一天执行。在Day-of-Week中,如果"L"单独存在,就等于7(星期六),否则代表当月内或者周内日期的最后一个实例。例如"* * * L 1 ? 2008"匹配2008-01-31(星期四);"* * * ? 1 L 2008"匹配2008-01-05(星期六)、2008-01-12(星期六)、2008-01-19(星期六)和2008-01-26(星期六)。
"W"可以放在Day-of-Month中。W 字符代表着工作日 (周一到周五),用来指定离指定日的最近的一个平日。例如,Day-of-Month中的 15W 意味着 "离该月15日的最近一个工作日"。如果15日是工作日,那么就在15日执行; 假如15日是星期六,那么会在14日(周五)执行;如果15日是周日,那么会在16日(周一)执行。
"#" 字符仅能用于Day-of-Week中。它用于指定月份中的第几周的哪一天。例如,如果你指定周域的值为 6#3,它意思是某月的第三个周五 (6=星期五,#3意味着月份中的第三周)。假如你指定 #5,然而月份中没有第 5 周,那么该月不会触发。
下面是个关于CronExpression的例子程序:
以上程序输出如下:
下面是个使用CronTrigger的例子:
在以上例子中,指定从每分钟的0秒起,每个5秒调度一次。此外还使用 CronTrigger 的 setStartTime方法 和 setEndTime方法限制了执行的时间范围。
CronTrigger支持的misfire instruction有MISFIRE_INSTRUCTION_SMART_POLICY(0),MISFIRE_INSTRUCTION_FIRE_ONCE_NOW(1)和MISFIRE_INSTRUCTION_DO_NOTHING(2)。其中MISFIRE_INSTRUCTION_SMART_POLICY等效于MISFIRE_INSTRUCTION_FIRE_ONCE_NOW。以下是关于misfire instruction的简单例子:
以上例子中,如果将trigger的miscfire instruction设置为MISFIRE_INSTRUCTION_DO_NOTHING,那么输出可能如下:
5 Calendar
跟 java.util.Calendar不同,Quartz Calendar用于指定一个时间区间,使 Trigger 在这个区间中不被触发。org.quartz.Calendar 接口中两个最重要的方法如下:
public long getNextIncludedTime(long timeStamp);
public boolean isTimeIncluded(long timeStamp);
Calendar 接口方法参数的类型是 long,这说明 Quartz Calender 能够排除的时间可以精确到毫秒级。要使用 Quartz Calendar,首先要把Calendar实例添加到Scheduler 中,然后在 Trigger 实例中指定关联的Calendar名字。
5.1 Builtin Calendars
Quartz 提供了以下常用的 Calender:
BaseCalender。为其它的Calender 实现了基本的功能。
WeeklyCalendar。 排除星期中的一天或多天。
MonthlyCalendar。 排除月的数天。
AnnualCalendar。排除年中一天或多天。
HolidayCalendar。特别用于排除特定节假日
下面是个使用AnnualCalendar的例子:
以上例子中,任务在每年的一月一日都不会被调度。
5.2 Customized Calendar
除了使用Quartz提供的Calendar,我们也可以创建定制的Calendar,例如创建一个 HourlyCalendar用于排除小时中的特定分钟。
以上例子中,只有奇数分钟内,任务才会被调度。
6 Listener
6.1 JobListener
JobListener 的定义如下:
getName() 方法返回一个字符串用以说明 JobListener 的名称。
Scheduler 在 JobDetail 将要被执行时调用jobToBeExecuted()方法。
Scheduler 在 JobDetail 即将被执行,却又被 TriggerListener 否决了时调用jobExecutionVetoed()方法。
Scheduler 在 JobDetail 被执行之后调用jobWasExecuted()方法。
下面是个关于JobListener的例子:
以上例子中,SimpleJobListener是作为一个非全局的JobListener注册到Scheduler的。首先调用Scheduler的addJobListener()方法,方法的参数是JobListener实例。然后对于任何引用到它的JobDetail,调用addJobListener()方法,方法的参数是JobListener的名称(也就是JobListener的getName()方法返回的名称)。如果需要注册一个全局的JobListener,只需要调用Scheduler的addGlobalJobListener()方法即可,这个JobListener就会和所有Job相关联。
6.2 TriggerListener
TriggerListener接口的定义如下:
和前面提到的 JobListener 一样,TriggerListner 接口的 getName() 返回一个字符串用以说明监听器的名称。
当与监听器相关联的 Trigger 被触发,Job 上的 execute() 方法将要被执行时,Scheduler调用triggerFired()方法。
Scheduler在 Trigger 触发后,Job 将要被执行时调用vetoJobExecution()方法。vetoJobExecution()方法给了TriggerListener 否决 Job 的执行的权力,如果返回 true,那么这个 Job 将不会为此次 Trigger的触发而得到执行。
Scheduler在 Trigger 错过触发时调用triggerMisfired() 方法。
Trigger 被触发并且完成了 Job 的执行时,Scheduler 调用triggerComplete()方法。
以下是个关于TriggerListener的例子:
以上例子中,SimpleTriggerListener是作为一个非全局的TriggerListener注册到Scheduler的。首先调用Scheduler的addTriggerListener()方法,方法的参数是TriggerListener实例。然后对于任何引用到它的Trigger,调用addTriggerListener ()方法,方法的参数是TriggerListener的名称(也就是TriggerListener的getName()方法返回的名称)。如果需要注册一个全局的TriggerListener,只需要调用Scheduler的addGlobalTriggerListener()方法即可,这个TriggerListener就会和所有Trigger相关联。以上程序的输出如下:
以上例子中,在偶数秒内调度的任务都被否决了。需要注意的是,如果TriggerListener中否决了某个任务,那么相应的triggerComplete()方法不会被调用。
6.3 SchedulerListener
SchedulerListener 接口包含了一系列的回调方法,它们会在 Scheduler 的生命周期中有关键事件发生时被调用。
Scheduler 在有新的 JobDetail 部署或卸载时调用jobScheduled() 和 jobUnscheduled()方法。
当一个 Trigger 到了再也不会触发的状态时调用triggerFinalized() 方法,除非与之关联 Job 已设置成了持久性,否则它就会从 Scheduler 中移除。
Scheduler 在发生在一个 Trigger 或 Trigger 组被暂停时调用triggersPaused() 方法。如果是 Trigger 组,那么triggerName 参数将为 null。
Scheduler 在发生成一个 Trigger 或 Trigger 组从暂停中恢复时调用triggersResumed() 方法。如果是 Trigger 组,那么triggerName 参数将为 null。
当一个或一组 JobDetail 暂停时调用jobsPaused() 方法方法。
当一个或一组 Job 从暂停上恢复时调用jobsResumed() 方法。如果是一个 Job 组,那么jobName 参数将为 null。
在 Scheduler 的正常运行期间产生一个严重错误时调用schedulerError() 方法。你可以使用 SchedulerException 的 getErrorCode() 或者 getUnderlyingException() 方法或获取到特定错误的更详尽的信息。
Scheduler 调用schedulerShutdown() 方法用来通知 SchedulerListener Scheduler 将要被关闭。
Quartz是一个开源的作业调度框架,可被集成到任何的Java EE 或者Java SE程序中。
2 Scheduler
通过SchedulerFactory接口创建Scheduler对象。当 Scheduler 实例被创建之后,就会被保存到一个仓库中(org.quartz.impl.SchedulerRepository)。Scheduler对象可以被start、standby和shutdown。一旦Scheduler被shutdown,那么不应该重新启动它。Scheduler对象被启动后,Triggers才会被触发。在Trigger被触发时,Scheduler会创建 Job 类的实例,执行实例的 execute() 方法并传入JobExecutionContext 上下文变量,JobExecutionContext封装了 Quartz 的运行时环境。
2.1 StdScheduler
可以通过调用以java.util.Properties为参数的initialize方法对StdSchedulerFactory实例进行配置。StdSchedulerFactory 还提供了一个静态方法 getDefaultScheduler()用来获得默认的Scheduler,假如之前未调用过任何一个 initialize() 方法,那么无参的 initialize() 方法会被调用。如果使用无参的 initialize 方法,StdSchedulerFactory 会执行以下几个步骤去尝试为工厂加载属性:
1. 检查System.getProperty("org.quartz.properties") 中是否设置了别的文件名;否则使用 quartz.properties 作为要加载的文件名。
2. 试图从当前工作目录中加载这个文件。
3. 试图从系统 classpath 下加载这个文件。这一步总是能成功的,因为在 Quartz Jar 包中有一个默认的 quartz.properties 文件。
以下是个quartz.properties 文件的例子:
#===============================================================
#Configure Main Scheduler Properties
#===============================================================
org.quartz.scheduler.instanceName = QuartzScheduler
org.quartz.scheduler.instanceId = AUTO
org.quartz.scheduler.rmi.export = false
org.quartz.scheduler.rmi.proxy = false
org.quartz.scheduler.wrapJobExecutionInUserTransaction = false
#===============================================================
#Configure ThreadPool
#===============================================================
org.quartz.threadPool.threadCount = 10
org.quartz.threadPool.threadPriority = 5
org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadsInheritContextClassLoaderOfInitializingThread = true
#===============================================================
#Configure JobStore
#===============================================================
org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore
org.quartz.jobStore.misfireThreshold = 60000
org.quartz.scheduler.instanceName用于指定Scheduler的实例名,可以是任意字符串。org.quartz.scheduler.instanceId用于指定实例ID,也可以是任意字符串。在集群环境中instanceId必须唯一。如果希望 Quartz 自动生成这个值,那么可以设置为 AUTO。如果 Quartz 框架是运行在非集群环境中,那么自动产生的值将会是 NON_CLUSTERED;如果是在集群环境下使用 Quartz,这个值将会是主机名加上当前的日期和时间。
org.quartz.threadPool.class属性值是一个实现了 org.quartz.spi.ThreadPool 接口的全限定类名。Quartz 自带的实现类是 org.quartz.smpl.SimpleThreadPool,它提供了固定大小的线程池,并经很好的测试过,能满足绝大多数情况下的需求。你也可以指定其它的线程池实现,例如需要一个可伸缩的线程池。
org.quartz.jobStore.class属性指定了在Scheduler的生命周期中,Job 和 Trigger 信息是如何被存储的。如果使用RAMJobStore,那么一旦调度器进程被终止,所有的 Job 和 Trigger 的状态就丢失了。除了RAMJobStore,还可以指定JDBCJobStore。虽然JDBCJobStore的性能不如RAMJobStore,但是可以持久地保存Job 和 Trigger 信息。
以下是个简单的例子:
public class DummyJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
final SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(sdf.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
SchedulerFactory schedulerFactory = new StdSchedulerFactory();
Scheduler scheduler = schedulerFactory.getScheduler();
scheduler.start();
JobDetail jobDetail = new JobDetail("myJob", null, DummyJob.class);
Trigger trigger = TriggerUtils.makeSecondlyTrigger(2);
trigger.setName("myTrigger");
scheduler.scheduleJob(jobDetail, trigger);
Thread.sleep(10000);
scheduler.shutdown();
}
}
3 Job
一个 Quartz Job 就是一个执行任务的 Java 类。Job 的实例要到该执行它们的时候才会实例化出来。这意味着 Job 不必担心线程安全性,因为同一时刻仅有一个线程去执行给定 Job 类的实例。Job有以下三个主要的属性:
易失性(volatility)。Job在程序关闭之后是否被持久化。 通过调用 JobDetail 的 setVolatility(boolean flag) 进行设置,默认值是 false。RamJobStore 使用的是非永久性存储器,所有关于 Job 和 Trigger 的信息会在程序关闭之后丢失。保存 Job 到 RamJobStore使得它们是易失性的。假如你需要让你的 Job 信息在程序重启之后仍能保留下来,你就该使用JDBCJobStore。
持久性(Durability)。 在所有的触发器触发之后,是否将Job从 JobStore 中移除。通过调用 JobDetail 的 setDurability(boolean flag) 方法设置,默认值是 false。假设设置了一个单次触发的 Trigger,触发之后它就变成了 STATE_COMPLETE 状态。这个 Trigger 指向的 Job 现在成了一个孤儿 Job,因为不再有任何 Trigger 与之相关联了。假如你设置这个Job为持久的,那么即使它成了孤儿 Job 也不会从 JobStore 移除掉。这样可以保证在将来,无论何时你的程序决定为这个 Job 增加另一个 Trigger 都是可用的。
可恢复性(Recovery)。当一个 Job 还在执行中,Scheduler 经历了一次非预期的关闭,在 Scheduler 重启之后该 Job 是否会重头开始再次被执行。通过调用 JobDetail 的 setRequestsRecovery(boolean flag)方法设置,默认值是 false。
3.1 JobDetail
实际上,并不是直接把 Job 对象注册到 Scheduler,而是注册一个 JobDetail 实例。JobDetail用于对Job进行配置。每当Trigger被触发时,Scheduler会创建相对应的Job的实例并调用其execute方法。传入的JobExecutionContext参数包含了该Job的运行时环境,例如得到相关的Scheduler、Trigger和JobDetail。
3.2 JobDataMap
由于每次调度Job的时候都有一个新的Job实例被创建,因此每次Job被调度后状态都丢失了。通过使用JobDataMap,可以向Job传递配置信息,或者保存多次调度之间的作业状态。JobDataMap 通过它的超类 org.quartz.util.DirtyFlagMap 实现了java.util.Map 接口。如果你使用的是持久化的JobStore(例如JDBCJobStore),那么JobDataMap中存放的数据必须能够被序列化。
可以在JobDetail和Trigger上设置JobDataMap。如果向 JobDataMap 中存入键/值对,那么这些数据可以在Job实例被执行时,通过传入参数JobExecutionContext中包含的Trigger和JobDetail实例访问到,因此这是一个向 Job实例传送配置的信息便捷方法。JobExecutionContext提供了一个方法getMergedJobDataMap,用于得到JobDetail和Trigger中包含的JobDataMap的合并后版本。需要注意的是,如果键/值对冲突,那么Trigger中包含的JobDataMap的值会覆盖掉JobDetail中包含的JobDataMap的值。以下是个简单的例子:
public class DummyJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
String name = context.getMergedJobDataMap().getString("name");
System.out.println(df.format(new Date()) + " Job executed, name: " + name);
}
public static void main(String args[]) throws Exception {
SchedulerFactory sf = new StdSchedulerFactory();
Scheduler scheduler = sf.getScheduler();
scheduler.start();
JobDetail jobDetail = new JobDetail("myJob", null, DummyJob.class);
jobDetail.getJobDataMap().put("name", "job1");
Trigger trigger = TriggerUtils.makeSecondlyTrigger(2);
trigger.setName("myTrigger");
scheduler.scheduleJob(jobDetail, trigger);
Thread.sleep(10000);
scheduler.shutdown();
}
}
3.3 Job
Job定义如下:
public interface Job {
execute(JobExecutionContext context) throws JobExecutionException;
}
每当Scheduler调度Job的时候,Scheduler根据配置的JobFactory创建一个新的Job实例。默认的JobFactory(org.quartz.simpl.SimpleJobFactory)只是通过反射,即调用Job类的newInstance方法构造Job实例,因此Job类需要有个可访问的无参构造函数。
3.4 StatefulJob
StatefulJob扩展Job,没有添加新的方法,其定义如下:
public interface StatefulJob extends Job {
}
当你需要在两次 Job 执行间维护状态的话,Quartz 框架为此提供了 org.quartz.StatefulJob 接口。Job 和 StatefulJob 存在以下两个关键差异:
JobDataMap 在每次执行之后重新持久化到 JobStore 中。这样就确保对stateful Job执行时对JobDataMap的修改都会保存,下次执行时也仍然可见。对于non-stateful Job,JobDataMap只是在JobDetail被注册到Scheduler的时候持久化到JobStore 中,这意味着每次non-stateful Job执行时对JobDataMap的修改都会被丢弃。
两个或多个有状态的 JobDetail 实例不能并发执行。如果有两个Trigger试图同时触发一个相同的stateful Job,那么其中一个Trigger会被阻塞,直到另外一个Trigger触发的Job执行完毕。这确保了不会对JobDataMap进行并发的修改,从而确保了线程安全。
下面是个使用StatefulJob接口的例子:
public class DummyStatefulJob implements StatefulJob {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
JobDataMap map = context.getJobDetail().getJobDataMap();
Integer round = (Integer)map.get("round");
if(round == null) {
round = new Integer(1);
} else {
round = new Integer(round.intValue() + 1);
}
map.put("round", round);
System.out.println(df.format(new Date()) + " Job executed, round: " + round);
}
public static void main(String args[]) throws Exception {
SchedulerFactory sf = new StdSchedulerFactory();
Scheduler scheduler = sf.getScheduler();
scheduler.start();
JobDetail jd = new JobDetail("myJob", null, DummyStatefulJob.class);
Trigger trigger = TriggerUtils.makeSecondlyTrigger(2);
trigger.setName("myTrigger");
scheduler.scheduleJob(jd, trigger);
Thread.sleep(10000);
scheduler.shutdown();
}
}
以上程序的输出如下:
2013-04-26 11:20:50.357 Job executed, round: 1
2013-04-26 11:20:52.357 Job executed, round: 2
2013-04-26 11:20:54.342 Job executed, round: 3
2013-04-26 11:20:56.342 Job executed, round: 4
2013-04-26 11:20:58.342 Job executed, round: 5
2013-04-26 11:21:00.342 Job executed, round: 6
3.5 InterruptableJob
InterruptableJob扩展Job,其定义如下:
public interface InterruptableJob extends Job {
void interrupt() throws UnableToInterruptJobException;
}
可以通过调用Scheduler 接口的interrupt(String jobName, String groupName) 方法来中断特定的Job。Scheduler会负责调用InterruptableJob的interrupt()方法。至于Job如何被中断,这要取决于Job的具体实现。下面是个使用InterruptableJob接口的例子:
public class DummyInterruptableJob implements InterruptableJob {
//
private final AtomicBoolean interrupted = new AtomicBoolean(false);
@Override
public void interrupt()
throws UnableToInterruptJobException {
interrupted.compareAndSet(false, true);
}
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
while(!interrupted.get()) {
System.out.println(df.format(new Date()) + " Job executing");
try {
Thread.sleep(1000);
} catch(Exception e) {
}
}
System.out.println(df.format(new Date()) + " Job interrupted");
}
public static void main(String args[]) throws Exception {
SchedulerFactory sf = new StdSchedulerFactory();
Scheduler scheduler = sf.getScheduler();
scheduler.start();
JobDetail jd = new JobDetail("job1", null, DummyInterruptableJob.class);
SimpleTrigger trigger = new SimpleTrigger("trigger1", null);
trigger.setRepeatCount(0);
scheduler.scheduleJob(jd, trigger);
Thread.sleep(5000);
scheduler.interrupt("job1", null);
scheduler.shutdown();
}
}
以上程序的输出如下:
2010-08-09 08:58:54.248 Job executing
2010-08-09 08:58:55.248 Job executing
2010-08-09 08:58:56.248 Job executing
2010-08-09 08:58:57.248 Job executing
2010-08-09 08:58:58.248 Job executing
2010-08-09 08:58:59.248 Job interrupted
需要注意的是,以上例子中构造JobDetail的第二个参数group为null(即使用默认的group),因此在调用Scheduler的interrupt()方法时的第二个参数(group)也必须为null。
4 Trigger
Job 包含了要执行任务的逻辑,Trigger 决定了Job 何时被执行。可以为单个Job 使用多个 Trigger,但一个 Trigger 只能被指派给一个 Job。Trigger上也可以配置JobDataMap,当Trigger触发时,被执行的Job实例可以获得Trigger所关联的JobDataMap。特别是当多个Trigger被关联到一个JobDetail时,可以通过Trigger所关联的JobDataMap向Job提供额外的配置信息。Quartz提供了多种Trigger实现,最常用的有SimpleTrigger、NthIncludeDayTrigger和CronTrigger。
某一时刻,假设有m个trigger可能被触发,但是只有n(m > n)个工作线程可用,那么具有最高优先级的n个trigger会优先被触发。通过Trigger的setPriority(int priority)方法可以调整Trigger的优先级,默认优先级是5。
Trigger的另外一个比较重要的属性是misfire instruction。由于scheduler被shutdown,trigger被pause或者没有可用的工作线程等原因,都会导致trigger没有被触发。不同类型的Trigger可以设置不同的misfire instruction。
4.1 SimpleTrigger
SimpleTrigger是最简单的一种 Trigger。 如果你需要某个Job在特定时间执行一次,或者在某个时间执行一次后再以特定的间隔重复执行 n 次,那么可以使用SimpleTrigger。SimpleTrigger包含以下属性:开始时间、结束时间、重复次数和重复间隔。重复次数可以是0、正整数或者SimpleTrigger.REPEAT_INDEFINITELY。重复间隔的单位是毫秒。如果设置了结束时间,那么它会覆盖重复次数,例如你设置了开始时间、结束时间和重复间隔,那么Quartz会自动计算重复次数。下面是个使用SimpleTrigger的例子:
public class SimpleTriggerJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
String startedTime = df.format(new Date());
try {
System.out.println("Job started, started time: " + startedTime);
Thread.sleep(3000);
} catch(Exception e) {
throw new JobExecutionException(e);
} finally {
System.out.println("Job stopped, started time: " + startedTime);
}
}
public static void main(String args[]) throws Exception {
//
Properties props = new Properties();
props.put(StdSchedulerFactory.PROP_THREAD_POOL_CLASS, "org.quartz.simpl.SimpleThreadPool");
props.put("org.quartz.threadPool.threadCount", "5");
StdSchedulerFactory factory = new StdSchedulerFactory();
factory.initialize(props);
Scheduler scheduler = factory.getScheduler();
scheduler.start();
//
JobDetail jd = new JobDetail("job1", "group1", SimpleTriggerJob.class);
SimpleTrigger trigger = new SimpleTrigger("trigger1", "group1");
trigger.setRepeatCount(2);
trigger.setRepeatInterval(1000);
scheduler.scheduleJob(jd, trigger);
//
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上程序的输出如下:
Job started, started time: 2013-04-26 09:29:37.765
Job started, started time: 2013-04-26 09:29:38.750
Job started, started time: 2013-04-26 09:29:39.750
Job stopped, started time: 2013-04-26 09:29:37.765
Job stopped, started time: 2013-04-26 09:29:38.750
Job stopped, started time: 2013-04-26 09:29:39.750
如果将以上例子中props的org.quartz.threadPool.threadCount属性设置为2(也就是说最多同时能执行2个Job),那么程序的输出如下:
Job started, started time: 2013-04-26 09:31:10.156
Job started, started time: 2013-04-26 09:31:11.125
Job stopped, started time: 2013-04-26 09:31:10.156
Job started, started time: 2013-04-26 09:31:13.156
Job stopped, started time: 2013-04-26 09:31:11.125
Job stopped, started time: 2013-04-26 09:31:13.156
从以上输出可以看出,本应该在09:31:12左右调度的第三个任务,由于没有可用的线程而被阻塞,直到第一个任务结束之后(09:31:13)才被调度。需要注意的是,如果给trigger设置不同的misfire instruction,可能会有不同的行为。
4.2 NthIncludeDayTrigger
NthIncludedDayTrigger用于在每一间隔类型的第几天执行 Job,例如要在每个月的 15 号执行特定的 Job。目前Quartz 支持的间隔类型有:INTERVAL_TYPE_WEEKLY、INTERVAL_TYPE_MONTHLY和INTERVAL_TYPE_YEARLY。下面是个使用NthIncludeDayTrigger的例子:
public class NthIncludedDayTriggerJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
JobDataMap map = context.getJobDetail().getJobDataMap();
String name = map.getString("name");
System.out.println(df.format(new Date()) + " Job executed, name: " + name);
}
public static void main(String args[]) throws Exception {
//
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
scheduler.start();
//
JobDetail jd = new JobDetail("job1", "group1", NthIncludedDayTriggerJob.class);
NthIncludedDayTrigger trigger = new NthIncludedDayTrigger("trigger1", "group1");
trigger.setN(15);
trigger.setIntervalType(NthIncludedDayTrigger.INTERVAL_TYPE_MONTHLY);
scheduler.scheduleJob(jd, trigger);
//
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上例子中,任务被配置成在每月15日执行。执行时间可以通过NthIncludedDayTrigger的setFireAtTime(String fireAtTime)方法设置,默认是12:00:00。
4.3 CronTrigger
SimpleTrigger 对于需要在指定的时间(毫秒级)执行的Job还是不错的,但是假如你的Job需要更复杂的执行计划时,可能需要使用CronTrigger 提供的更灵活的功能。
CronExpression用于配置CronTrigger,它封装了一个字符串,这个字符串由空格分割的7个子表达式构成,它们分别代表:
1. Seconds
2. Minutes
3. Hours
4. Day-of-Month
5. Month
6. Day-of-Week
7. Year (可选)
例如"0 0 12 ? * WED"代表每周三的12点,"* * * ? * *"则代表每秒都执行。每个子表达式都有可选值的集合:Seconds和Minutes的可选值是0到59;Hours的可选值是0到23;Day-of-Month的可选值是1到31;Months的可选值是0到11,或者使用JAN、FEB、MAR、APR、MAY、JUN、JUL、AUG、SEP、OCT、NOV和DEC;Days-of-Week的可选值是1到7(1代表周日),或者是SUN、MON、TUE、WED、THU、FRI和SAT。每个子表达式也可以包含范围和列表。例如"MON-FRI"代表一个范围,即周一到周五;"MON, WED, FRI"代表一个列表,即周一、周三和周五;"MON-WED,SAT"代表周一、周二、周三和周六。
CronExpression表达式支持用特殊字符来创建更为复杂的执行计划。下面是可以在CronExpression中使用的特殊字符:
通配符"*"代表每一个可能的值。
"/"用于指定值的增量,例如Minutes字段上的"0/15"代表从0分钟起每隔15分钟。
"?"可以放在Day-of-Month和Day-of-Week中。"?"表示这个字段不包含具体值。所以如果指定Day-of-Month,那么可以在Day-of-Week字段中设置"?",表示Day-of-Week值无关紧要。
"L"可以放在Day-of-Month和Day-of-Week中。Day-of-Month表示在当月最后一天执行。在Day-of-Week中,如果"L"单独存在,就等于7(星期六),否则代表当月内或者周内日期的最后一个实例。例如"* * * L 1 ? 2008"匹配2008-01-31(星期四);"* * * ? 1 L 2008"匹配2008-01-05(星期六)、2008-01-12(星期六)、2008-01-19(星期六)和2008-01-26(星期六)。
"W"可以放在Day-of-Month中。W 字符代表着工作日 (周一到周五),用来指定离指定日的最近的一个平日。例如,Day-of-Month中的 15W 意味着 "离该月15日的最近一个工作日"。如果15日是工作日,那么就在15日执行; 假如15日是星期六,那么会在14日(周五)执行;如果15日是周日,那么会在16日(周一)执行。
"#" 字符仅能用于Day-of-Week中。它用于指定月份中的第几周的哪一天。例如,如果你指定周域的值为 6#3,它意思是某月的第三个周五 (6=星期五,#3意味着月份中的第三周)。假如你指定 #5,然而月份中没有第 5 周,那么该月不会触发。
下面是个关于CronExpression的例子程序:
public class CronExpressionTest {
public static void main(String args[]) throws Exception {
//
String expression[] = new String[]{
"* * * 4W 1 ? 2008",
"* * * 5W 1 ? 2008",
"* * * 6W 1 ? 2008",
"* * * 7W 1 ? 2008",
"* * * LW 1 ? 2008",
"* * * L 1 ? 2008",
"* * * ? 1 L 2008",
"* * * ? 1 0L 2008",
"* * * ? 1 1L 2008",
"* * * ? 1 2L 2008",
"* * * ? 1 3L 2008",
"* * * ? 1 4L 2008",
"* * * ? 1 5L 2008",
"* * * ? 1 6L 2008",
"* * * ? 1 7L 2008",
"* * * ? 1 1#1 2008",
"* * * ? 1 1#2 2008",
"* * * ? 1 1#3 2008",
"* * * ? 1 1#4 2008",
"* * * ? 1 1#5 2008"
};
//
for(int i = 0; i < expression.length; i++) {
System.out.println("######################");
CronExpression cp = new CronExpression(expression[i]);
for(int j = 0; j <= 31; j++) {
Date d = getDate(2008, 1, j);
if(cp.isSatisfiedBy(d)) {
System.out.println(cp.getCronExpression() + " matches " + print(d));
}
}
}
}
private static String print(Date date) {
SimpleDateFormat d = new SimpleDateFormat("yyyy-MM-dd(E)");
return d.format(date);
}
private static Date getDate(int year, int month, int dayOfMonth) {
Calendar c = Calendar.getInstance();
c.set(Calendar.YEAR, year);
c.set(Calendar.MONTH, month - 1);
c.set(Calendar.DAY_OF_MONTH, dayOfMonth);
return c.getTime();
}
}
以上程序输出如下:
######################
* * * 4W 1 ? 2008 matches 2008-01-04(星期五)
######################
* * * 5W 1 ? 2008 matches 2008-01-04(星期五)
######################
* * * 6W 1 ? 2008 matches 2008-01-07(星期一)
######################
* * * 7W 1 ? 2008 matches 2008-01-07(星期一)
######################
* * * LW 1 ? 2008 matches 2008-01-31(星期四)
######################
* * * L 1 ? 2008 matches 2008-01-31(星期四)
######################
* * * ? 1 L 2008 matches 2008-01-05(星期六)
* * * ? 1 L 2008 matches 2008-01-12(星期六)
* * * ? 1 L 2008 matches 2008-01-19(星期六)
* * * ? 1 L 2008 matches 2008-01-26(星期六)
######################
* * * ? 1 0L 2008 matches 2008-01-26(星期六)
######################
* * * ? 1 1L 2008 matches 2008-01-27(星期日)
######################
* * * ? 1 2L 2008 matches 2008-01-28(星期一)
######################
* * * ? 1 3L 2008 matches 2008-01-29(星期二)
######################
* * * ? 1 4L 2008 matches 2008-01-30(星期三)
######################
* * * ? 1 5L 2008 matches 2008-01-31(星期四)
######################
* * * ? 1 6L 2008 matches 2008-01-25(星期五)
######################
* * * ? 1 7L 2008 matches 2008-01-26(星期六)
######################
* * * ? 1 1#1 2008 matches 2008-01-06(星期日)
######################
* * * ? 1 1#2 2008 matches 2008-01-13(星期日)
######################
* * * ? 1 1#3 2008 matches 2008-01-20(星期日)
######################
* * * ? 1 1#4 2008 matches 2008-01-27(星期日)
######################
下面是个使用CronTrigger的例子:
public class CronTriggerJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(df.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
//
Properties props = new Properties();
props.put(StdSchedulerFactory.PROP_THREAD_POOL_CLASS, "org.quartz.simpl.SimpleThreadPool");
props.put("org.quartz.threadPool.threadCount", "2");
StdSchedulerFactory factory = new StdSchedulerFactory();
factory.initialize(props);
Scheduler scheduler = factory.getScheduler();
scheduler.start();
//
Date startTime = new Date();
Date endTime = new Date(startTime.getTime() + 20 * 1000);
//
JobDetail jd = new JobDetail("job1", "group1", CronTriggerJob.class);
CronTrigger trigger = new CronTrigger("trigger1", "group1");
CronExpression cronExpression = new CronExpression("0/5 * * * * ?");
trigger.setCronExpression(cronExpression);
trigger.setStartTime(startTime);
trigger.setEndTime(endTime);
scheduler.scheduleJob(jd, trigger);
//
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
在以上例子中,指定从每分钟的0秒起,每个5秒调度一次。此外还使用 CronTrigger 的 setStartTime方法 和 setEndTime方法限制了执行的时间范围。
CronTrigger支持的misfire instruction有MISFIRE_INSTRUCTION_SMART_POLICY(0),MISFIRE_INSTRUCTION_FIRE_ONCE_NOW(1)和MISFIRE_INSTRUCTION_DO_NOTHING(2)。其中MISFIRE_INSTRUCTION_SMART_POLICY等效于MISFIRE_INSTRUCTION_FIRE_ONCE_NOW。以下是关于misfire instruction的简单例子:
public class SimpleTriggerListener implements TriggerListener {
//
private String name;
private DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
public SimpleTriggerListener(String name) {
this.name = name;
}
public String getName() {
return name;
}
public void triggerFired(Trigger trigger, JobExecutionContext context) {
System.out.println(dateFormat.format(new Date()) + " triggerFired, trigger name: " + trigger.getName());
}
public void triggerMisfired(Trigger trigger) {
System.out.println(dateFormat.format(new Date()) + " triggerMisfired, trigger name: " + trigger.getName());
}
public void triggerComplete(Trigger trigger, JobExecutionContext context, int triggerInstructionCode) {
System.out.println(dateFormat.format(new Date()) + " triggerComplete, trigger name: " + trigger.getName());
}
public boolean vetoJobExecution(Trigger trigger, JobExecutionContext context) {
return false;
}
}
public class CronTriggerJob implements StatefulJob {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
Integer round = (Integer)context.getJobDetail().getJobDataMap().get("round");
if(round == null) {
round = new Integer(1);
} else {
round = new Integer(round.intValue() + 1);
}
context.getJobDetail().getJobDataMap().put("round", round);
System.out.println(df.format(new Date()) + " Job executed, round: " + round);
}
public static void main(String args[]) throws Exception {
//
Properties props = new Properties();
props.put(StdSchedulerFactory.PROP_THREAD_POOL_CLASS, "org.quartz.simpl.SimpleThreadPool");
props.put("org.quartz.threadPool.threadCount", "5");
props.put("org.quartz.jobStore.misfireThreshold", "1000");
StdSchedulerFactory factory = new StdSchedulerFactory();
factory.initialize(props);
Scheduler scheduler = factory.getScheduler();
SimpleTriggerListener stl = new SimpleTriggerListener("triggerListener1");
scheduler.addTriggerListener(stl);
scheduler.start();
//
Date startTime = new Date();
Date endTime = new Date(startTime.getTime() + 6 * 1000);
//
JobDetail jd = new JobDetail("job1", "group1", CronTriggerJob.class);
CronTrigger trigger = new CronTrigger("trigger1", "group1");
CronExpression cronExpression = new CronExpression("0/1 * * * * ?");
trigger.setCronExpression(cronExpression);
trigger.setStartTime(startTime);
trigger.setEndTime(endTime);
trigger.addTriggerListener(stl.getName());
trigger.setMisfireInstruction(CronTrigger.MISFIRE_INSTRUCTION_SMART_POLICY);
scheduler.scheduleJob(jd, trigger);
//
Thread.sleep(2000);
System.out.println("start to pause trigger");
scheduler.pauseTrigger("trigger1", "group1");
Thread.sleep(2500);
System.out.println("start to resume trigger");
scheduler.resumeTrigger("trigger1", "group1");
Thread.sleep(2000);
System.out.println("start to shutdown scheduler");
scheduler.shutdown();
}
}
以上例子中,如果将trigger的miscfire instruction设置为MISFIRE_INSTRUCTION_DO_NOTHING,那么输出可能如下:
2010-08-09 14:34:50.890 triggerFired, trigger name: trigger1
2010-08-09 14:34:50.890 Job executed, round: 1
2010-08-09 14:34:50.890 triggerComplete, trigger name: trigger1
2010-08-09 14:34:51.015 triggerFired, trigger name: trigger1
2010-08-09 14:34:51.015 Job executed, round: 2
2010-08-09 14:34:51.015 triggerComplete, trigger name: trigger1
2010-08-09 14:34:52.015 triggerFired, trigger name: trigger1
2010-08-09 14:34:52.015 Job executed, round: 3
2010-08-09 14:34:52.015 triggerComplete, trigger name: trigger1
start to pause trigger
start to resume trigger
2010-08-09 14:34:55.390 triggerMisfired, trigger name: trigger1
2010-08-09 14:34:56.000 triggerFired, trigger name: trigger1
2010-08-09 14:34:56.000 Job executed, round: 4
2010-08-09 14:34:56.000 triggerComplete, trigger name: trigger1
start to shutdown scheduler
如果将trigger的miscfire instruction设置为MISFIRE_INSTRUCTION_SMART_POLICY或者MISFIRE_INSTRUCTION_FIRE_ONCE_NOW,那么输出可能如下:
2010-08-09 14:35:20.921 triggerFired, trigger name: trigger1
2010-08-09 14:35:20.921 Job executed, round: 1
2010-08-09 14:35:20.921 triggerComplete, trigger name: trigger1
2010-08-09 14:35:21.015 triggerFired, trigger name: trigger1
2010-08-09 14:35:21.015 Job executed, round: 2
2010-08-09 14:35:21.015 triggerComplete, trigger name: trigger1
2010-08-09 14:35:22.015 triggerFired, trigger name: trigger1
2010-08-09 14:35:22.015 Job executed, round: 3
2010-08-09 14:35:22.015 triggerComplete, trigger name: trigger1
start to pause trigger
start to resume trigger
2010-08-09 14:35:25.421 triggerMisfired, trigger name: trigger1
2010-08-09 14:35:25.421 triggerFired, trigger name: trigger1
2010-08-09 14:35:25.421 Job executed, round: 4
2010-08-09 14:35:25.421 triggerComplete, trigger name: trigger1
2010-08-09 14:35:26.000 triggerFired, trigger name: trigger1
2010-08-09 14:35:26.000 Job executed, round: 5
2010-08-09 14:35:26.000 triggerComplete, trigger name: trigger1
start to shutdown scheduler
5 Calendar
跟 java.util.Calendar不同,Quartz Calendar用于指定一个时间区间,使 Trigger 在这个区间中不被触发。org.quartz.Calendar 接口中两个最重要的方法如下:
public long getNextIncludedTime(long timeStamp);
public boolean isTimeIncluded(long timeStamp);
Calendar 接口方法参数的类型是 long,这说明 Quartz Calender 能够排除的时间可以精确到毫秒级。要使用 Quartz Calendar,首先要把Calendar实例添加到Scheduler 中,然后在 Trigger 实例中指定关联的Calendar名字。
5.1 Builtin Calendars
Quartz 提供了以下常用的 Calender:
BaseCalender。为其它的Calender 实现了基本的功能。
WeeklyCalendar。 排除星期中的一天或多天。
MonthlyCalendar。 排除月的数天。
AnnualCalendar。排除年中一天或多天。
HolidayCalendar。特别用于排除特定节假日
下面是个使用AnnualCalendar的例子:
public class AnnualCalendarJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(df.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
//
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
scheduler.start();
//
JobDetail jd = new JobDetail("job1", "group1", AnnualCalendarJob.class);
//
Calendar c = Calendar.getInstance();
c.set(Calendar.MONTH, Calendar.JANUARY);
c.set(Calendar.DATE, 1);
AnnualCalendar ac = new AnnualCalendar();
ac.setDayExcluded(c, true);
scheduler.addCalendar("calendar1", ac, true, true);
//
CronTrigger trigger = new CronTrigger("trigger1", "group1");
CronExpression cronExpression = new CronExpression("0/5 * * * * ?");
trigger.setCronExpression(cronExpression);
trigger.setCalendarName("calendar1");
scheduler.scheduleJob(jd, trigger);
//
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上例子中,任务在每年的一月一日都不会被调度。
5.2 Customized Calendar
除了使用Quartz提供的Calendar,我们也可以创建定制的Calendar,例如创建一个 HourlyCalendar用于排除小时中的特定分钟。
public class HourlyCalendar extends BaseCalendar {
//
private static final long serialVersionUID = -4438834879438520769L;
//
private CopyOnWriteArrayList<Integer> excludedMinutes = new CopyOnWriteArrayList<Integer>();
/**
*
*/
public HourlyCalendar() {
super();
}
public HourlyCalendar(Calendar baseCalendar) {
super(baseCalendar);
}
/**
*
*/
public boolean isTimeIncluded(long msec) {
//
if (super.isTimeIncluded(msec) == false) {
return false;
}
//
final java.util.Calendar cal = createJavaCalendar(msec);
int minute = cal.get(java.util.Calendar.MINUTE);
return !(isMinuteExcluded(minute));
}
public long getNextIncludedTime(long msec) {
//
long baseTime = super.getNextIncludedTime(msec);
if ((baseTime > 0) && (baseTime > msec)) {
msec = baseTime;
}
//
final java.util.Calendar cal = getStartOfSecond(msec);
int minute = cal.get(java.util.Calendar.MINUTE);
if (isMinuteExcluded(minute) == false) {
return msec;
}
//
while (isMinuteExcluded(minute) == true) {
cal.add(java.util.Calendar.MINUTE, 1);
minute = cal.get(java.util.Calendar.MINUTE);
}
return cal.getTime().getTime();
}
public List<Integer> getMinutesExcluded() {
return excludedMinutes;
}
public void setMinuteExcluded(int minute) {
if (isMinuteExcluded(minute)) {
return;
}
excludedMinutes.add(new Integer(minute));
}
public void setMinutesExcluded(List<Integer> minutes) {
if (minutes == null) {
this.excludedMinutes.clear();
} else {
this.excludedMinutes.addAll(minutes);
}
}
public boolean isMinuteExcluded(int minute) {
for(Integer excludedMinute : this.excludedMinutes) {
if (minute == excludedMinute.intValue()) {
return true;
}
}
return false;
}
/**
*
*/
private java.util.Calendar getStartOfSecond(long msec) {
final java.util.Calendar c = (super.getTimeZone() == null) ? java.util.Calendar.getInstance() : java.util.Calendar.getInstance(getTimeZone());
c.setTimeInMillis(msec);
c.set(java.util.Calendar.SECOND, 0);
c.set(java.util.Calendar.MILLISECOND, 0);
return c;
}
}
public class HourlyCalendarJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(df.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
//
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
scheduler.start();
//
JobDetail jd = new JobDetail("job1", "group1", HourlyCalendarJob.class);
//
HourlyCalendar cal = new HourlyCalendar();
for (int i = 0; i < 60; i++) {
if (i % 2 == 0) {
cal.setMinuteExcluded(i);
}
}
//
long now = System.currentTimeMillis();
for(int i = 0; i < 100; i++) {
long next = cal.getNextIncludedTime(now);
System.out.println(new Date(next));
}
scheduler.addCalendar("hourlyCalendar1", cal, true, true);
//
CronTrigger trigger = new CronTrigger("trigger1", "group1");
CronExpression cronExpression = new CronExpression("0/5 * * * * ?");
trigger.setCronExpression(cronExpression);
trigger.setCalendarName("hourlyCalendar1");
scheduler.scheduleJob(jd, trigger);
//
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while (true) {
String line = br.readLine();
if (line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上例子中,只有奇数分钟内,任务才会被调度。
6 Listener
6.1 JobListener
JobListener 的定义如下:
public interface JobListener{
String getName();
void jobToBeExecuted(JobExecutionContext context);
void jobExecutionVetoed(JobExecutionContext context);
void jobWasExecuted(JobExecutionContext context, JobExecutionException jobException);
}
getName() 方法返回一个字符串用以说明 JobListener 的名称。
Scheduler 在 JobDetail 将要被执行时调用jobToBeExecuted()方法。
Scheduler 在 JobDetail 即将被执行,却又被 TriggerListener 否决了时调用jobExecutionVetoed()方法。
Scheduler 在 JobDetail 被执行之后调用jobWasExecuted()方法。
下面是个关于JobListener的例子:
public class SimpleJobListener implements JobListener {
//
private String name;
public SimpleJobListener(String name) {
this.name = name;
}
public String getName() {
return name;
}
public void jobToBeExecuted(JobExecutionContext context) {
System.out.println("jobToBeExecuted, job name: " + context.getJobDetail().getName());
}
public void jobExecutionVetoed(JobExecutionContext context) {
System.out.println("jobExecutionVetoed, job name: " + context.getJobDetail().getName());
}
public void jobWasExecuted(JobExecutionContext context, JobExecutionException jobException) {
System.out.println("jobWasExecuted, job name: " + context.getJobDetail().getName());
}
}
public class ListenerJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(df.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
scheduler.start();
SimpleJobListener sjl = new SimpleJobListener("listener1");
scheduler.addJobListener(sjl);
JobDetail jd = new JobDetail("job1", "group1", ListenerJob.class);
jd.addJobListener(sjl.getName());
SimpleTrigger trigger = new SimpleTrigger("trigger1", "group1");
trigger.setRepeatCount(3);
trigger.setRepeatInterval(1000);
scheduler.scheduleJob(jd, trigger);
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上例子中,SimpleJobListener是作为一个非全局的JobListener注册到Scheduler的。首先调用Scheduler的addJobListener()方法,方法的参数是JobListener实例。然后对于任何引用到它的JobDetail,调用addJobListener()方法,方法的参数是JobListener的名称(也就是JobListener的getName()方法返回的名称)。如果需要注册一个全局的JobListener,只需要调用Scheduler的addGlobalJobListener()方法即可,这个JobListener就会和所有Job相关联。
6.2 TriggerListener
TriggerListener接口的定义如下:
public interface TriggerListener {
String getName();
void triggerFired(Trigger trigger, JobExecutionContext context);
boolean vetoJobExecution(Trigger trigger, JobExecutidonContext context);
void triggerMisfired(Trigger trigger);
void triggerComplete(Trigger trigger, JobExecutionContext context, int triggerInstructionCode);
}
和前面提到的 JobListener 一样,TriggerListner 接口的 getName() 返回一个字符串用以说明监听器的名称。
当与监听器相关联的 Trigger 被触发,Job 上的 execute() 方法将要被执行时,Scheduler调用triggerFired()方法。
Scheduler在 Trigger 触发后,Job 将要被执行时调用vetoJobExecution()方法。vetoJobExecution()方法给了TriggerListener 否决 Job 的执行的权力,如果返回 true,那么这个 Job 将不会为此次 Trigger的触发而得到执行。
Scheduler在 Trigger 错过触发时调用triggerMisfired() 方法。
Trigger 被触发并且完成了 Job 的执行时,Scheduler 调用triggerComplete()方法。
以下是个关于TriggerListener的例子:
public class SimpleTriggerListener implements TriggerListener {
//
private String name;
public SimpleTriggerListener(String name) {
this.name = name;
}
public String getName() {
return name;
}
public void triggerFired(Trigger trigger, JobExecutionContext context) {
System.out.println("triggerFired, trigger name: " + trigger.getName());
}
public void triggerMisfired(Trigger trigger) {
System.out.println("triggerMisfired, trigger name: " + trigger.getName());
}
public void triggerComplete(Trigger trigger, JobExecutionContext context, int triggerInstructionCode) {
System.out.println("triggerComplete, trigger name: " + trigger.getName());
}
public boolean vetoJobExecution(Trigger trigger, JobExecutionContext context) {
boolean r = (System.currentTimeMillis() / 1000) % 2 == 0;
System.out.println("vetoJobExecution, trigger name: " + trigger.getName() + ", voted: " + r);
return r;
}
}
public class ListenerJob implements Job {
@Override
public void execute(JobExecutionContext context)
throws JobExecutionException {
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
System.out.println(df.format(new Date()) + " Job executed");
}
public static void main(String args[]) throws Exception {
Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
scheduler.start();
SimpleJobListener sjl = new SimpleJobListener("jobListener1");
scheduler.addJobListener(sjl);
SimpleTriggerListener stl = new SimpleTriggerListener("triggerListener1");
scheduler.addTriggerListener(stl);
JobDetail jd = new JobDetail("job1", "group1", ListenerJob.class);
jd.addJobListener(sjl.getName());
SimpleTrigger trigger = new SimpleTrigger("trigger1", "group1");
trigger.setRepeatCount(100);
trigger.setRepeatInterval(500);
trigger.addTriggerListener(stl.getName());
scheduler.scheduleJob(jd, trigger);
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
while(true) {
String line = br.readLine();
if(line.equalsIgnoreCase("quit")) {
break;
}
}
br.close();
scheduler.shutdown();
}
}
以上例子中,SimpleTriggerListener是作为一个非全局的TriggerListener注册到Scheduler的。首先调用Scheduler的addTriggerListener()方法,方法的参数是TriggerListener实例。然后对于任何引用到它的Trigger,调用addTriggerListener ()方法,方法的参数是TriggerListener的名称(也就是TriggerListener的getName()方法返回的名称)。如果需要注册一个全局的TriggerListener,只需要调用Scheduler的addGlobalTriggerListener()方法即可,这个TriggerListener就会和所有Trigger相关联。以上程序的输出如下:
triggerFired, trigger name: trigger1
vetoJobExecution, trigger name: trigger1, voted: false
jobToBeExecuted, job name: job1
2010-08-09 11:39:25.546 Job executed
jobWasExecuted, job name: job1
triggerComplete, trigger name: trigger1
triggerFired, trigger name: trigger1
vetoJobExecution, trigger name: trigger1, voted: true
jobExecutionVetoed, job name: job1
以上例子中,在偶数秒内调度的任务都被否决了。需要注意的是,如果TriggerListener中否决了某个任务,那么相应的triggerComplete()方法不会被调用。
6.3 SchedulerListener
SchedulerListener 接口包含了一系列的回调方法,它们会在 Scheduler 的生命周期中有关键事件发生时被调用。
public interface SchedulerListener {
void jobScheduled(Trigger trigger);
void jobUnscheduled(String triggerName, String triggerGroup);
void triggerFinalized(Trigger trigger);
void triggersPaused(String triggerName, String triggerGroup);
void triggersResumed(String triggerName,String triggerGroup);
void jobsPaused(String jobName, String jobGroup);
void jobsResumed(String jobName, String jobGroup);
void schedulerError(String msg, SchedulerException cause);
void schedulerShutdown();
}
Scheduler 在有新的 JobDetail 部署或卸载时调用jobScheduled() 和 jobUnscheduled()方法。
当一个 Trigger 到了再也不会触发的状态时调用triggerFinalized() 方法,除非与之关联 Job 已设置成了持久性,否则它就会从 Scheduler 中移除。
Scheduler 在发生在一个 Trigger 或 Trigger 组被暂停时调用triggersPaused() 方法。如果是 Trigger 组,那么triggerName 参数将为 null。
Scheduler 在发生成一个 Trigger 或 Trigger 组从暂停中恢复时调用triggersResumed() 方法。如果是 Trigger 组,那么triggerName 参数将为 null。
当一个或一组 JobDetail 暂停时调用jobsPaused() 方法方法。
当一个或一组 Job 从暂停上恢复时调用jobsResumed() 方法。如果是一个 Job 组,那么jobName 参数将为 null。
在 Scheduler 的正常运行期间产生一个严重错误时调用schedulerError() 方法。你可以使用 SchedulerException 的 getErrorCode() 或者 getUnderlyingException() 方法或获取到特定错误的更详尽的信息。
Scheduler 调用schedulerShutdown() 方法用来通知 SchedulerListener Scheduler 将要被关闭。