Quartz手册 - Lesson2

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。