Table of Contents | ‹ Lesson 1 | ‹ Lesson 3 |
Lesson 2: The Quartz API, Jobs And Triggers
The Quartz API
The key interfaces of the Quartz API are:
- Scheduler - the main API for interacting with the scheduler.
- Job - an interface to be implemented by components that you wish to have executed by the scheduler.
- JobDetail - used to define instances of Jobs.
- Trigger - a component that defines the schedule upon which a given Job will be executed.
- JobBuilder - used to define/build JobDetail instances, which define instances of Jobs.
- TriggerBuilder - used to define/build Trigger instances.
Quartz關鍵API：
- Scheduler - 同scheduler交互的核心API
- Job - 實現Job接口的組件能夠被scheduler執行
- JobDetail - 用來定義Jobs實例
- Trigger - 描述任務執行的時間表
- JobBuilder - 用來定義/創建JobDetail的實例
- TriggerBuilder - 用來定義/創建Trigger的實例
A Scheduler’s life-cycle is bounded by it’s creation, via a SchedulerFactory and a call to its shutdown() method. Once created the Scheduler interface can be used add, remove, and list Jobs and Triggers, and perform other scheduling-related operations (such as pausing a trigger). However, the Scheduler will not actually act on any triggers (execute jobs) until it has been started with the start() method, as shown in Lesson 1.
Scheduler的生命週期從通過SchedulerFactory創建開始，直到調用其shutdown方法結束。創建Scheduler後，可以通過其接口添加、移除、查詢Jobs和Triggers和其他調度操作（例如終止一個trigger）。然而正如Lesson1中描述的那樣，Scheduler在調用start()方法啓動之前不會激活任何triggers（執行jobs）。
Quartz provides “builder” classes that define a Domain Specific Language (or DSL, also sometimes referred to as a “fluent interface”). In the previous lesson you saw an example of it, which we present a portion of here again:
Quartz提供"builder"類來定義一種領域特定語言DSL。我們再看一下之前舉得例子：
// 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);
The block of code that builds the job definition is using methods that were statically imported from the JobBuilder class. Likewise, the block of code that builds the trigger is using methods imported from the TriggerBuilder class - as well as from the SimpleScheduleBuilder class.
例子中通過靜態導入的JobBuilder類中的方法創建了JobDetail。同樣的，trigger也是通過靜態導入的SimpleScheduleBuilder類創建的。
The static imports of the DSL can be achieved through import statements such as these:
import static org.quartz.JobBuilder.*;
import static org.quartz.SimpleScheduleBuilder.*;
import static org.quartz.CronScheduleBuilder.*;
import static org.quartz.CalendarIntervalScheduleBuilder.*;
import static org.quartz.TriggerBuilder.*;
import static org.quartz.DateBuilder.*;
The various “ScheduleBuilder” classes have methods relating to defining different types of schedules.
SchedulerBuilder類可以根據不同的方法創建不同的Schedules。
The DateBuilder class contains various methods for easily constructing java.util.Date instances for particular points in time (such as a date that represents the next even hour - or in other words 10:00:00 if it is currently 9:43:27).
DateBuilder類提供了很多方法來創建java.util.Date的實例來構建特殊的時間點。
Jobs and Triggers
A Job is a class that implements the Job interface, which has only one simple method:
一個任務需要實現Job接口，Job接口只有一個方法：
The Job Interface
package org.quartz;
public interface Job {
public void execute(JobExecutionContext context)
throws JobExecutionException;
}
When the Job’s trigger fires (more on that in a moment), the execute(..) method is invoked by one of the scheduler’s worker threads. The JobExecutionContext object that is passed to this method provides the job instance with information about its “run-time” environment - a handle to the Scheduler that executed it, a handle to the Trigger that triggered the execution, the job’s JobDetail object, and a few other items.
當Job達到trigger點的時候，scheduler的工作線程會調用Job的execute(..)方法。其中參數中的JobExecutionContext對象描述了任務的運行時環境 - 執行它的Scheduler、執行它的Trigger、任務的JobDetail對象和其他的一些元素。
The JobDetail object is created by the Quartz client (your program) at the time the Job is added to the scheduler. It contains various property settings for the Job, as well as a JobDataMap, which can be used to store state information for a given instance of your job class. It is essentially the definition of the job instance, and is discussed in further detail in the next lesson.
JobDetail是客戶端在將任務添加到scheduler時創建的。它設置了job的一系列屬性，也稱爲JobDataMap，可以保存job實例的信息。JobDetail本質上就是Job的實例，接下來的章節會討論它。
Trigger objects are used to trigger the execution (or ‘firing’) of jobs. When you wish to schedule a job, you instantiate a trigger and ‘tune’ its properties to provide the scheduling you wish to have. Triggers may also have a JobDataMap associated with them - this is useful to passing parameters to a Job that are specific to the firings of the trigger. Quartz ships with a handful of different trigger types, but the most commonly used types are SimpleTrigger and CronTrigger.
Trigger對象用來觸發job的執行。當你想調度一個任務的時候，你需要實例化一個trigger對象並且合適的調整它的屬性。Triggers也有自己的JobDataMap，可以將參數傳遞給Job。Quartz提供了不同類型的trigger，最常用的是SimpleTrigger和CronTrigger。
SimpleTrigger is handy if you need ‘one-shot’ execution (just single execution of a job at a given moment in time), or if you need to fire a job at a given time, and have it repeat N times, with a delay of T between executions. CronTrigger is useful if you wish to have triggering based on calendar-like schedules - such as “every Friday, at noon” or “at 10:15 on the 10th day of every month.”
SimpleTrigger適用於只執行一次的任務場景，或者是延時重複執行多次的場景。CronTrigger適用於日曆樣時間的任務，例如"每週五中午"或"每月10號的10:15"。
Why Jobs AND Triggers? Many job schedulers do not have separate notions of jobs and triggers. Some define a ‘job’ as simply an execution time (or schedule) along with some small job identifier. Others are much like the union of Quartz’s job and trigger objects. While developing Quartz, we decided that it made sense to create a separation between the schedule and the work to be performed on that schedule. This has (in our opinion) many benefits.
爲什麼有Jobs和Triggers？許多定時任務工具沒有單獨的jobs或triggers的概念，他們簡單的將job定義爲執行時間（其上運行了一些任務）。其他的工具聯合了Quartz的任務和trigger對象。因此在設計Quartz的時候，我們設計了調度和任務。在我們看來，這樣有許多優勢。
For example, Jobs can be created and stored in the job scheduler independent of a trigger, and many triggers can be associated with the same job. Another benefit of this loose-coupling is the ability to configure jobs that remain in the scheduler after their associated triggers have expired, so that that it can be rescheduled later, without having to re-define it. It also allows you to modify or replace a trigger without having to re-define its associated job.
例如，任務可以獨立於調度來創建和存儲，不同的調度可以作用於同一個任務。這種鬆耦合設計的另一個好處是我們可以單獨的對任務或者對調度進行修改。
Identities
Jobs and Triggers are given identifying keys as they are registered with the Quartz scheduler. The keys of Jobs and Triggers (JobKey and TriggerKey) allow them to be placed into ‘groups’ which can be useful for organizing your jobs and triggers into categories such as “reporting jobs” and “maintenance jobs”. The name portion of the key of a job or trigger must be unique within the group - or in other words, the complete key (or identifier) of a job or trigger is the compound of the name and group.
Jobs和Triggers在註冊到Quartz scheduler的時候有可以有自己的標識。jobs和triggers的key（JobKey和TriggerKey）允許他們被『groups』進行分組，這樣可以很方便的通過類目來組織jobs和triggers（例如"reporting job"和"maintenance jobs"）。job和trigger的key必須是同group唯一的。換而言之，name和group合起來標識了唯一的job或trigger。
You now have a general idea about what Jobs and Triggers are, you can learn more about them in Lesson 3: More About Jobs & JobDetails and Lesson 4: More About Triggers.
現在你已經基本瞭解了Jobs和Triggers。接下來你可以學習Lesson3和Lesson4。