725
Quartz教程三：Job與JobDetail介紹
本係列教程由quartz-2.2.x官方文檔翻譯、整理而來，希望給同樣對quartz感興趣的朋友一些參考和幫助，有任何不當或錯誤之處，歡迎指正；有興趣研究源碼的同學，可以參考我對quartz-core源碼的注釋(進行中)。
正如在教程二中講到的，Job實現起來很容易，該接口隻有一個“execute”方法。本節主要關注：Job的特點、Job接口的execute方法以及JobDetail。
你定義了一個實現Job接口的類，這個類僅僅表明該job需要完成什麼類型的任務，除此之外，Quartz還需要知道該Job實例所包含的屬性；這將由JobDetail類來完成。
JobDetail實例是通過JobBuilder類創建的，導入該類下的所有靜態方法，會讓你編碼時有DSL的感覺：
import static org.quartz.JobBuilder.*;讓我們先看看Job的特征（nature）以及Job實例的生命期。不妨先回頭看看教程一中的代碼片段：
// define the job and tie it to our HelloJob class
JobDetail job = newJob(HelloJob.class)
.withIdentity("myJob", "group1") // name "myJob", group "group1"
.build();
// Trigger the job to run now, and then every 40 seconds
Trigger trigger = newTrigger()
.withIdentity("myTrigger", "group1")
.startNow()
.withSchedule(simpleSchedule()
.withIntervalInSeconds(40)
.repeatForever())
.build();
// Tell quartz to schedule the job using our trigger
sched.scheduleJob(job, trigger);
“HelloJob”類可以如下定義：
public class HelloJob implements Job {
public HelloJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
System.err.println("Hello! HelloJob is executing.");
}
}
可以看到，我們傳給scheduler一個JobDetail實例，因為我們在創建JobDetail時，將要執行的job的類名傳給了JobDetail，所以scheduler就知道了要執行何種類型的job；每次當scheduler執行job時，在調用其execute(…)方法之前會創建該類的一個新的實例；執行完畢，對該實例的引用就被丟棄了，實例會被垃圾回收；這種執行策略帶來的一個後果是，job必須有一個無參的構造函數（當使用默認的JobFactory時）；另一個後果是，在job類中，不應該定義有狀態的數據屬性，因為在job的多次執行中，這些屬性的值不會保留。
那麼如何給job實例增加屬性或配置呢？如何在job的多次執行中，跟蹤job的狀態呢？答案就是:JobDataMap，JobDetail對象的一部分。
JobDataMap
JobDataMap中可以包含不限量的（序列化的）數據對象，在job實例執行的時候，可以使用其中的數據；JobDataMap是Java Map接口的一個實現，額外增加了一些便於存取基本類型的數據的方法。
將job加入到scheduler之前，在構建JobDetail時，可以將數據放入JobDataMap，如下示例：
JobDetail job = newJob(DumbJob.class)
.withIdentity("myJob", "group1") // name "myJob", group "group1"
.usingJobData("jobSays", "Hello World!")
.usingJobData("myFloatValue", 3.141f)
.build();
在job的執行過程中，可以從JobDataMap中取出數據，如下示例：
public class DumbJob implements Job {
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
JobKey key = context.getJobDetail().getKey();
JobDataMap dataMap = context.getJobDetail().getJobDataMap();
String jobSays = dataMap.getString("jobSays");
float myFloatValue = dataMap.getFloat("myFloatValue");
System.err.println("Instance " + key + " of DumbJob says: " + jobSays + ", and val is: " + myFloatValue);
}
}
如果你使用的是持久化的存儲機製（本教程的JobStore部分會講到），在決定JobDataMap中存放什麼數據的時候需要小心，因為JobDataMap中存儲的對象都會被序列化，因此很可能會導致類的版本不一致的問題；Java的標準類型都很安全，如果你已經有了一個類的序列化後的實例，某個時候，別人修改了該類的定義，此時你需要確保對類的修改沒有破壞兼容性；更多細節，參考現實中的序列化問題。另外，你也可以配置JDBC-JobStore和JobDataMap，使得map中僅允許存儲基本類型和String類型的數據，這樣可以避免後續的序列化問題。
如果你在job類中，為JobDataMap中存儲的數據的key增加set方法（如在上麵示例中，增加setJobSays(String val)方法），那麼Quartz的默認JobFactory實現在job被實例化的時候會自動調用這些set方法，這樣你就不需要在execute()方法中顯式地從map中取數據了。
在Job執行時，JobExecutionContext中的JobDataMap為我們提供了很多的便利。它是JobDetail中的JobDataMap和Trigger中的JobDataMap的並集，但是如果存在相同的數據，則後者會覆蓋前者的值。
下麵的示例，在job執行時，從JobExecutionContext中獲取合並後的JobDataMap：
public class DumbJob implements Job {
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
JobKey key = context.getJobDetail().getKey();
JobDataMap dataMap = context.getMergedJobDataMap(); // 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 " + key + " of DumbJob says: " + jobSays + ", and val is: " + myFloatValue);
}
}
如果你希望使用JobFactory實現數據的自動“注入”，則示例代碼為：
public class DumbJob implements Job {
String jobSays;
float myFloatValue;
ArrayList state;
public DumbJob() {
}
public void execute(JobExecutionContext context)
throws JobExecutionException
{
JobKey key = context.getJobDetail().getKey();
JobDataMap dataMap = context.getMergedJobDataMap(); // Note the difference from the previous example
state.add(new Date());
System.err.println("Instance " + key + " of DumbJob says: " + jobSays + ", and val is: " + myFloatValue);
}
public void setJobSays(String jobSays) {
this.jobSays = jobSays;
}
public void setMyFloatValue(float myFloatValue) {
myFloatValue = myFloatValue;
}
public void setState(ArrayList state) {
state = state;
}
}
你也許發現，整體上看代碼更多了，但是execute()方法中的代碼更簡潔了。而且，雖然代碼更多了，但如果你的IDE可以自動生成setter方法，你就不需要寫代碼調用相應的方法從JobDataMap中獲取數據了，所以你實際需要編寫的代碼更少了。當前，如何選擇，由你決定。
Job實例
很多用戶對於Job實例到底由什麼構成感到很迷惑。我們在這裏解釋一下，並在接下來的小節介紹job狀態和並發。
你可以隻創建一個job類，然後創建多個與該job關聯的JobDetail實例，每一個實例都有自己的屬性集和JobDataMap，最後，將所有的實例都加到scheduler中。
比如，你創建了一個實現Job接口的類“SalesReportJob”。該job需要一個參數（通過JobdataMap傳入），表示負責該銷售報告的銷售員的名字。因此，你可以創建該job的多個實例（JobDetail），比如“SalesReportForJoe”、“SalesReportForMike”，將“joe”和“mike”作為JobDataMap的數據傳給對應的job實例。
當一個trigger被觸發時，與之關聯的JobDetail實例會被加載，JobDetail引用的job類通過配置在Scheduler上的JobFactory進行初始化。默認的JobFactory實現，僅僅是調用job類的newInstance()方法，然後嚐試調用JobDataMap中的key的setter方法。你也可以創建自己的JobFactory實現，比如讓你的IOC或DI容器可以創建/初始化job實例。
在Quartz的描述語言中，我們將保存後的JobDetail稱為“job定義”或者“JobDetail實例”,將一個正在執行的job稱為“job實例”或者“job定義的實例”。當我們使用“job”時，一般指代的是job定義，或者JobDetail；當我們提到實現Job接口的類時，通常使用“job類”。
Job狀態與並發
關於job的狀態數據（即JobDataMap）和並發性，還有一些地方需要注意。在job類上可以加入一些注解，這些注解會影響job的狀態和並發性。
@DisallowConcurrentExecution：將該注解加到job類上，告訴Quartz不要並發地執行同一個job定義（這裏指特定的job類）的多個實例。請注意這裏的用詞。拿前一小節的例子來說，如果“SalesReportJob”類上有該注解，則同一時刻僅允許執行一個“SalesReportForJoe”實例，但可以並發地執行“SalesReportForMike”類的一個實例。所以該限製是針對JobDetail的，而不是job類的。但是我們認為（在設計Quartz的時候）應該將該注解放在job類上，因為job類的改變經常會導致其行為發生變化。
@PersistJobDataAfterExecution：將該注解加在job類上，告訴Quartz在成功執行了job類的execute方法後（沒有發生任何異常），更新JobDetail中JobDataMap的數據，使得該job（即JobDetail）在下一次執行的時候，JobDataMap中是更新後的數據，而不是更新前的舊數據。和 @DisallowConcurrentExecution注解一樣，盡管注解是加在job類上的，但其限製作用是針對job實例的，而不是job類的。由job類來承載注解，是因為job類的內容經常會影響其行為狀態（比如，job類的execute方法需要顯式地“理解”其”狀態“）。
如果你使用了@PersistJobDataAfterExecution注解，我們強烈建議你同時使用@DisallowConcurrentExecution注解，因為當同一個job（JobDetail）的兩個實例被並發執行時，由於競爭，JobDataMap中存儲的數據很可能是不確定的。
Job的其它特性
通過JobDetail對象，可以給job實例配置的其它屬性有：
- Durability：如果一個job是非持久的，當沒有活躍的trigger與之關聯的時候，會被自動地從scheduler中刪除。也就是說，非持久的job的生命期是由trigger的存在與否決定的；
- RequestsRecovery：如果一個job是可恢複的，並且在其執行的時候，scheduler發生硬關閉（hard shutdown)（比如運行的進程崩潰了，或者關機了），則當scheduler重新啟動的時候，該job會被重新執行。此時，該job的JobExecutionContext.isRecovering() 返回true。
JobExecutionException
最後，是關於Job.execute(..)方法的一些額外細節。execute方法中僅允許拋出一種類型的異常（包括RuntimeExceptions），即JobExecutionException。因此，你應該將execute方法中的所有內容都放到一個”try-catch”塊中。你也應該花點時間看看JobExecutionException的文檔，因為你的job可以使用該異常告訴scheduler，你希望如何來處理發生的異常。
最後更新：2017-05-23 17:03:41