关键字: quartz 定时 调度
这篇文章是英文教程的中文翻译,有些认为暂时使用不到的特性有省略,英文文档参见http://www.opensymphony.com/quartz/wikidocs/TutorialLesson1.html。
如何使用
使用QUARTZ调试程序之前,必须使用SchedlerFactory实例化Scheduler。一旦实例化Scheduler后可以启动或者停止,需要注意的是一旦Scheduler关闭,必须重新实例化后才能够重启。任务只有在Scheduler启动后才会执行。
下面的代码片断实例化并启动Scheduler,然后执行一个任务。
- SchedulerFactory schedFact = new org.quartz.impl.StdSchedulerFactory();
- Scheduler sched = schedFact.getScheduler();
- sched.start();
- JobDetail jobDetail = new JobDetail("myJob", null, DumbJob.class);
- Trigger trigger = TriggerUtils.makeHourlyTrigger(); // fire every hour
- trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date()));
- trigger.setName("myTrigger");
- sched.scheduleJob(jobDetail, trigger);
SchedulerFactory schedFact = new org.quartz.impl.StdSchedulerFactory();
Scheduler sched = schedFact.getScheduler();
sched.start();
JobDetail jobDetail = new JobDetail("myJob", null, DumbJob.class);
Trigger trigger = TriggerUtils.makeHourlyTrigger(); // fire every hour
trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date()));
trigger.setName("myTrigger");
sched.scheduleJob(jobDetail, trigger);
任务/触发器
要定义一个任务,只需要实现Job接口即可,Job接口如下:
- package org.quartz;public interface Job { public void execute(JobExecutionContext context)
- throws JobExecutionException;
- }
package org.quartz;public interface Job { public void execute(JobExecutionContext context)
throws JobExecutionException;
}
当任务被触发时将调用execute方法,JobExecutionContext 参数提供关于任务的运行时环境,包括一个Scheduler的引用,触发这个任务的触发器的引用,任务的JobDetail实例和一些别的信息。
JobDetail 对象在添加任务到Scheduler时创建,这个对象和*JobDataMap* 都用来保存Job实例的状态信息。
Trigger 用来触发任务。要计划一个任务,需要实例化一个触发器并设置相关的属性,触发器也有一个关联的JobDataMap用来传递参数给指定的任务。Quartz提供几个不同的触发器实例,比较常用的是SimpleTrigger和CronTrigger。
如果需要在一个指定的时间,或者指定的时间后以一个指定的间隔对一个任务重复执行多次,使用SimpleTrigger。如果需要基于日历安排任务,使用CronTrigger,比如每个星期五中午。
很多任务调用器没有分离任务和触发器,Quartz这样做有很多好处。比如一个任务可以和多个触发器关联,可以更改或替换一个触发器,而不必重新定义任务。
任务和触发器都有唯一标识名称,也可以进行分组,在一个组中任务和触发器的名称必须是唯一的,这意味着任务和触发器是使用名称+组名唯一标识的。如果不指定组名,相当于使用缺省的组名: Scheduler.DEFAULT_GROUP 。
任务
以前的Quartz要求具体的Job实现类通过get/set方法传递数据,现在使用JobDetail类来传递数据。
我们先来看一个实例:
- JobDetail jobDetail = new JobDetail("myJob", // job name
- sched.DEFAULT_GROUP, // job group (you can also specify 'null' to use the default group)
- DumbJob.class); // the java class to executeTrigger trigger = TriggerUtils.makeDailyTrigger(8, 30);
- trigger.setStartTime(new Date());
- trigger.setName("myTrigger");sched.scheduleJob(jobDetail, trigger);
JobDetail jobDetail = new JobDetail("myJob", // job name
sched.DEFAULT_GROUP, // job group (you can also specify 'null' to use the default group)
DumbJob.class); // the java class to executeTrigger trigger = TriggerUtils.makeDailyTrigger(8, 30);
trigger.setStartTime(new Date());
trigger.setName("myTrigger");sched.scheduleJob(jobDetail, trigger);
如下是DumbJob类的代码:
- public class DumbJob implements Job {
- public DumbJob() {
- }
- public void execute(JobExecutionContext context)
- throws JobExecutionException
- {
- System.err.println("DumbJob is executing.");
- }
- }
public class DumbJob implements Job {
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
System.err.println("DumbJob is executing.");
}
}
注意在添加一个任务时,传递了一个JobDetail实例作为参数,构建这个JobDetail实例时需要一个任务类参数。每次调用程序执行任务时,创建一个新的任务类实例并执行其execute方法,但是这种方法有一些限制,首先是所有的任务实现必须提供一个无参数的构造函数,还有就是任务实现不应该包含成员字段,因为在每次执行后这些值都会被消除。
那么应该如何给一个任务提供属性或者配置呢?如何在任务的不同执行过程中保存或跟踪任务的状态呢?这是通过JobDetail的JobDataMap来实现。
JobDataMap
JobDataMap可以用来保存任何需要传递给任务实例的对象(这些对象要求是可序列化的),JobDataMap是java的Map接口的实现,添加了一些便利方法,下面的代码片断描述了如何使用JobDataMap保存数据:
- jobDetail.getJobDataMap().put("jobSays", "Hello World!");
- jobDetail.getJobDataMap().put("myFloatValue", 3.141f);
- jobDetail.getJobDataMap().put("myStateData", new ArrayList());
jobDetail.getJobDataMap().put("jobSays", "Hello World!");
jobDetail.getJobDataMap().put("myFloatValue", 3.141f);
jobDetail.getJobDataMap().put("myStateData", new ArrayList());
下面的示例描述了如何在任务执行过程中从JobDataMap获取数据:
- public class DumbJob implements Job {
- public DumbJob() {
- }
- public void execute(JobExecutionContext context)
- throws JobExecutionException
- {
- String instName = context.getJobDetail().getName();
- String instGroup = context.getJobDetail().getGroup();
- JobDataMap dataMap = context.getJobDetail().getJobDataMap();
- String jobSays = dataMap.getString("jobSays");
- float myFloatValue = dataMap.getFloat("myFloatValue");
- ArrayList state = (ArrayList)dataMap.get("myStateData");
- state.add(new Date());
- System.err.println("Instance " + instName + " of DumbJob says: " + jobSays);
- }
- }
public class DumbJob implements Job {
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
String instName = context.getJobDetail().getName();
String instGroup = context.getJobDetail().getGroup();
JobDataMap dataMap = context.getJobDetail().getJobDataMap();
String jobSays = dataMap.getString("jobSays");
float myFloatValue = dataMap.getFloat("myFloatValue");
ArrayList state = (ArrayList)dataMap.get("myStateData");
state.add(new Date());
System.err.println("Instance " + instName + " of DumbJob says: " + jobSays);
}
}
如果使用可持久化的JobStore(随后会有讨论),需要小心决定将JobDataMap保存在什么地方,因为JobDataMap对象中保存的对象是可序列化的,因此可能会遇到类版本问题。
有状态/无状态
触发器也可以使用JobDataMap保存数据。当需要使用多个触发器重用保存在Scheduler中的单个任务实例时,并且针对每个触发器希望提供任务不同的数据时,这是比较有用的。
JobDataMap在任务执行过程中,可以在JobExecutionContext中找到,这里的JobDataMap是JobDetail中的JobDataMap和触发器中的JobDataMap合并的结果,如果遇到命名相同的元素,后者会重写前者。
如下是从JobExecutionContext中获取JobDataMap的代码片断:
- public class DumbJob implements Job {
- public DumbJob() {
- }
- public void execute(JobExecutionContext context)
- throws JobExecutionException
- {
- String instName = context.getJobDetail().getName();
- String instGroup = context.getJobDetail().getGroup();
- JobDataMap dataMap = context.getJobDataMap(); // Note the difference from the previous example
- String jobSays = dataMap.getString("jobSays");
- float myFloatValue = dataMap.getFloat("myFloatValue");
- ArrayList state = (ArrayList)dataMap.get("myStateData");
- state.add(new Date());
- System.err.println("Instance " + instName + " of DumbJob says: " + jobSays);
- }
- }
public class DumbJob implements Job {
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
String instName = context.getJobDetail().getName();
String instGroup = context.getJobDetail().getGroup();
JobDataMap dataMap = context.getJobDataMap(); // Note the difference from the previous example
String jobSays = dataMap.getString("jobSays");
float myFloatValue = dataMap.getFloat("myFloatValue");
ArrayList state = (ArrayList)dataMap.get("myStateData");
state.add(new Date());
System.err.println("Instance " + instName + " of DumbJob says: " + jobSays);
}
}
有状态任务
任务可以被定义成有状态或无状态的,无状态任务仅仅通过JobDataMap传递数据,这意味着每次任务执行后对JobDataMap的改变都会丢失,而有状态任务恰恰相反,每次任务执行后JobDataMap都被恢复。有状态任务不能并发执行。
实现*StatefulJob*接口的任务是有状态的
任务属性
下面是通过JobDetail对象定义的一些任务属性:
Durability - 如果这个值为false,每次任务没有活动的触发器关联时都将从Scheduler中删除。
Volatility - 如果任务是暂态的,在每次重启Scheduler时将不会被持久化RequestsRecovery - 如果任务是"requests recovery",当他在Scheduler关闭的时间正在执行时,当Scheduler再次启动时将再次被执行。
JobListeners - 任务可以添加多个JobListener实例,当任务执行时,这些监听器将接收到通知。
JobExecutionException - Job的execute方法只能抛出JobExecutionException,这就意味着通常你需要try-catch方法中的所有代码。详细信息可以参考JAVADOC。
触发器
Calendars
Quartz Calendar 对象 (不是 java.util.Calendar对象) 可以和触发器关联,当需要从触发器中排除一些时间时,Calendar是比较有用的。比如你希望创建一个触发器,在每个星期三的上午九点激活一个任务,然后通过加一个Calendar实例排除所有的节假日。Calendar接口如下:
- package org.quartz;
- public interface Calendar
- {
- public boolean isTimeIncluded(long timeStamp);
- public long getNextIncludedTime(long timeStamp);
- }
package org.quartz;
public interface Calendar
{
public boolean isTimeIncluded(long timeStamp);
public long getNextIncludedTime(long timeStamp);
}
注意这些方法的参数单位是微秒,这意味着Calendar可以精确到微秒,但是通常我们只关心天,Quartz提供一个org.quartz.impl.HolidayCalendar类用来简化Calendar的使用。
Calendar必须使用Scheduler的addCalendar方法进行注册。如果使用HolidayCalendar,实例化后应该调用addExcludedDate(Date date)添加那些需要排除的日期,同一个Calendar可以用于多个触发器。
- HolidayCalendar cal = new HolidayCalendar();
- cal.addExcludedDate( someDate );
- sched.addCalendar("myHolidays", cal, false);
- Trigger trigger = TriggerUtils.makeHourlyTrigger(); // fire every one hour interval
- trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date())); // start on the next even hour
- trigger.setName("myTrigger1");
- trigger.setCalendarName("myHolidays"); // .. schedule job with trigger
- Trigger trigger2 = TriggerUtils.makeDailyTrigger(8, 0); // fire every day at 08:00
- trigger.setStartTime(new Date()); // begin immediately
- trigger2.setName("myTrigger2");
- trigger2.setCalendarName("myHolidays"); // .. schedule job with trigger2
HolidayCalendar cal = new HolidayCalendar();
cal.addExcludedDate( someDate );
sched.addCalendar("myHolidays", cal, false);
Trigger trigger = TriggerUtils.makeHourlyTrigger(); // fire every one hour interval
trigger.setStartTime(TriggerUtils.getEvenHourDate(new Date())); // start on the next even hour
trigger.setName("myTrigger1");
trigger.setCalendarName("myHolidays"); // .. schedule job with trigger
Trigger trigger2 = TriggerUtils.makeDailyTrigger(8, 0); // fire every day at 08:00
trigger.setStartTime(new Date()); // begin immediately
trigger2.setName("myTrigger2");
trigger2.setCalendarName("myHolidays"); // .. schedule job with trigger2
TriggerUtils
TriggerUtils 类包含一些创建触发器和日期的便利方法。使用这个类可以很容易的创建基于分钟,小时,天,星期,月的触发器。
TriggerListener
触发器也可以注册监听器,监听器必须实现*TriggerListener* 接口。
SimpleTrigger
如果需要计划一个任务在指定的时间执行,或者在指定的时间后以指定的间隔连续执行多次,比如希望在2005年1月12号上午11:22:54开始执行一个任务,在这之后每隔20分钟执行一次,共执行一次,这种情况下可以使用SimpleTrigger。
SimpleTrigger包含几个属性:开始时间,结束时间,重复次数和间隔。
重复次数可以是大于等于0,或者是常量值SimpleTrigger.REPEAT_INDEFINITELY,间隔必须大于等于0的长整数,单位是微秒。如果间隔为0表示并发执行重复次数。
如果不熟悉java.util.Calendar类,可能经常需要根据开始时间计算触发时间,org.quartz.helpers.TriggerUtils 可以帮助完成这些任务。
结束时间属性重写重复次数属性。如果希望创建一个触发器,每隔10秒执行一次,直到一个指定的时间,可以简单的指定结束时间, 重复次数值为REPEAT_INDEFINITELY。
SimpleTrigger有几个构造函数,下面是其中一个:
- public SimpleTrigger(String name,
- String group,
- Date startTime,
- Date endTime,
- int repeatCount,
- long repeatInterval)
public SimpleTrigger(String name,
String group,
Date startTime,
Date endTime,
int repeatCount,
long repeatInterval)
创建一个10秒钟后只执行一次的触发器:
- long startTime = System.currentTimeMillis() + 10000L;
- SimpleTrigger trigger = new SimpleTrigger("myTrigger",
- null,
- new Date(startTime),
- null,
- 0,
- 0L);
long startTime = System.currentTimeMillis() + 10000L;
SimpleTrigger trigger = new SimpleTrigger("myTrigger",
null,
new Date(startTime),
null,
0,
0L);
创建一个每隔60秒重复执行的触发器:
- SimpleTrigger trigger = new SimpleTrigger("myTrigger",
- null,
- new Date(),
- null,
- SimpleTrigger.REPEAT_INDEFINITELY,
- 60L * 1000L);
SimpleTrigger trigger = new SimpleTrigger("myTrigger",
null,
new Date(),
null,
SimpleTrigger.REPEAT_INDEFINITELY,
60L * 1000L);
创建一个40秒后开始执行,每隔10秒执行一次的触发器:
- long endTime = System.currentTimeMillis() + 40000L;
- SimpleTrigger trigger = new SimpleTrigger("myTrigger",
- "myGroup",
- new Date(),
- new Date(endTime),
- SimpleTrigger.REPEAT_INDEFINITELY,
- 10L * 1000L);
long endTime = System.currentTimeMillis() + 40000L;
SimpleTrigger trigger = new SimpleTrigger("myTrigger",
"myGroup",
new Date(),
new Date(endTime),
SimpleTrigger.REPEAT_INDEFINITELY,
10L * 1000L);
创建一个触发器,在2002年3月17日开始执行,重复5次,每次间隔为30秒:
- java.util.Calendar cal = new java.util.GregorianCalendar(2002, cal.MARCH, 17);
- cal.set(cal.HOUR, 10);
- cal.set(cal.MINUTE, 30);
- cal.set(cal.SECOND, 0);
- cal.set(cal.MILLISECOND, 0); Data startTime = cal.getTime() SimpleTrigger trigger = new SimpleTrigger("myTrigger",
- null,
- startTime,
- null,
- 5,
- 30L * 1000L);
java.util.Calendar cal = new java.util.GregorianCalendar(2002, cal.MARCH, 17);
cal.set(cal.HOUR, 10);
cal.set(cal.MINUTE, 30);
cal.set(cal.SECOND, 0);
cal.set(cal.MILLISECOND, 0); Data startTime = cal.getTime() SimpleTrigger trigger = new SimpleTrigger("myTrigger",
null,
startTime,
null,
5,
30L * 1000L);
CronTrigger
如果需要基于日历指定触发器,可以使用CronTrigger。使用CronTrigger可以实现类似的触发器,比如:每个星期五的下午。比如每个星期一,三和五的上午9点到10点之间每隔5分钟。
CronTrigger也有一个开始时间和结束时间属性,用来指定什么时候任务开始和结束。
Cron表达式:*Cron*表达式用来配置CronTrigger。Cron表达式是一个由七个部分组成的字符串,这七个部分用空隔进行分隔:
Seconds
Minutes
Hours
Day-of-Month (月内日期)
Month
Day-of-Week (周内日期)
Year (可选字段)
每个字段都有一些有效值。比如秒和分可以取值0-59,小时可以取值0-23。Day-of-Month可以取值0-31,需要注意一个月有多少天。 月可以取值0-11,或者通过使用JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV 和 DEC。 Days-of-Week可以取值1-7(1==Sunday)或者SUN, MON, TUE, WED, THU, FRI 和SAT。
'/' 字符可以用来指定增量,比如如果指定Minute字段为"0/15"表示在第0分钟启动,每隔15分钟的间隔;"3/20"表示每三分钟启动,每隔20分钟的间隔。
'?' 字符可以在day-of-month和day-of-week 字段中使用。问号表示这个字段不包含具体值。所以,如果指定月内日期,可以在周内日期字段中插入“?”,表示周内日期值无关紧要。
'L'字符可以在day-of-month和day-of-week 字段中使用,这个字符表示最后一个的意思。比如在day-of-month字段中表示这个月的最后一天,如果在day-of-week字段表示"7"或者"SAT",但是如果在day-of-week字段L在另一个值后面,意味着这个月的最后XXX天,比如"6L"表示这个月的最后一个星期五。使用这个字符,不能指定列表,范围值。
'W'字符用来指定离指定天最近的星期XXX,比如如果day-of-month字段值为"15W",表示离这个月15号最近的一个
weekday。
'#'字符用来表示这个月的第几个XXX,比如day-of-week字段的"6#3"表示这个月的第三个星期五。
'*'字符表示是通配字符,表示该字段可以接受任何可能的值,比如Day-Of-Week字段的*表示每天。
下面是一些示例:
创建一个每五分钟激活一次的触发器:
- "0 0/5 * * * ?"
"0 0/5 * * * ?"
创建一个触发器在当前分钟的第10秒后,每五分钟执行一次,比如上午10:00:10 am,上午10:05:10:
- "10 0/5 * * * ?"
"10 0/5 * * * ?"
创建一个触发器,在每个星期三和星期五的10:30, 11:30, 12:30, 和13:30执行。
- "0 30 10-13 ? * WED,FRI"
"0 30 10-13 ? * WED,FRI"
创建一个触发器,在每个月的第5天和第20天的上午8点到10点执行,每隔半小时执行一次,注意上午10:00不会执行:
- "0 0/30 8-9 5,20 * ?"
"0 0/30 8-9 5,20 * ?"
监听器
基于触发器的监听器接口如下:
- public interface TriggerListener {
- public String getName();
- public void triggerFired(Trigger trigger, JobExecutionContext context);
- public boolean vetoJobExecution(Trigger trigger, JobExecutionContext context);
- public void triggerMisfired(Trigger trigger);
- public void triggerComplete(Trigger trigger, JobExecutionContext context,
- int triggerInstructionCode);
- }
public interface TriggerListener {
public String getName();
public void triggerFired(Trigger trigger, JobExecutionContext context);
public boolean vetoJobExecution(Trigger trigger, JobExecutionContext context);
public void triggerMisfired(Trigger trigger);
public void triggerComplete(Trigger trigger, JobExecutionContext context,
int triggerInstructionCode);
}
基于任务的监听器接口如下:
- public interface JobListener {
- public String getName();
- public void jobToBeExecuted(JobExecutionContext context);
- public void jobExecutionVetoed(JobExecutionContext context);
- public void jobWasExecuted(JobExecutionContext context,
- JobExecutionException jobException);
- }
public interface JobListener {
public String getName();
public void jobToBeExecuted(JobExecutionContext context);
public void jobExecutionVetoed(JobExecutionContext context);
public void jobWasExecuted(JobExecutionContext context,
JobExecutionException jobException);
}
注册监听器
要创建一个监听器,只需要实现相应的接口就可以了。监听器需要在Scheduler中注册,监听器可以被注册为全局的或者本地的,注册监听器时必须指定一个名字,或者监听器本身的getName方法返回一个值。
- scheduler.addGlobalJobListener(myJobListener);
- or
- scheduler.addJobListener(myJobListener);