Lesson 2: The Quartz API, Jobs And Triggers

http://www.quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/tutorial-lesson-02.html

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.

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.

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 API 关键的几个接口：

          Scheduler：跟任务调度相关的最主要的API接口。

          Job：你期望任务调度执行的组件定义（调度器执行的内容），都必须实现该接口。

          JobDetail：用来定义Job的实例。

          Trigger：定义一个指定的Job何时被执行的组件，也叫触发器。

          JobBuilder：用来定义或创建JobDetail的实例，JobDetail限定了只能是Job的实例。

          TriggerBuilder：用来定义或创建触发器的实例。

 

        调度器的生命周期，起始于SchedulerFactory的创建，终止于调用shutdown方法。当调度器接口实例创建完成后，就可以添加，删除和查询Jobs和Triggers对象，也可以执行其它的跟调度器相关的操作，比如中止触发器的触发。并且，调度器在调用start方法之前，不会触发任何一个触发器去执行作业任务，如第一课所示的例子。

          Quartz框架提供许多构造器类来定义一套领域特定语言，简称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 SimpleScheduleBulder class.

The static imports of the DSL can be achieved through import statements such as these:

生成Job定义调用的方法代码块静态地导入了JobBuilder类，同样地，生成触发器调用的方法代码块静态地导入了TriggerBuilder类，SimpleScheduleBuilder类也是静态导入的。

         DSL静态导入的实现可以通过以下几个import语句完成：

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.

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).

功能各样的ScheduleBuilder类提供多种方法来定义不同类型的调度器。

          DateBuilder类包含了许多方法可以更简捷地构建java.util.Date实例对象，尤其针对特定的时间点，比如下一个的整点时间，换言之现在是9:43:27，我需要得到10:00:00的时间对象。

Jobs and Triggers

A Job is a class that implements the Job interface, which has only one simple method:

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.

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.

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.

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.”

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.

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.

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.

当作业任务的触发器被触发的那一刻，调度器的一个工作线程，将会调用该Job的execute方法。JobExecutionContext对象会向execute方法传递运行时环境的工作任务信息：执行该方法的调度器引用，触发该方法执行的触发器引用，Job实例的JobDetail对象，以及一些其它信息。

        当调度器添加Job实例时，会在Quartz客户端程序中（咱们自己开发的代码）创建JobDetail对象。JobDetail为Job实例提供了许多设置属性，以及JobDataMap成员变量属性，它用来存储特定Job实例的状态信息。这是从本质上定义Job实例，我们将会在下一节中深入地讨论相关的细节。

        触发器对象用来触发Job对象的执行，当你希望调度一项作业任务，你可以实例化一个触发器并且将触发时间属性调整为你期望的时间表。触发器也可以关联JobDataMap对象，可以非常方便地将具体的被触发的触发器当作参数传递给Job实例。

          Quartz框架附带少数不同类型的触发器，但最常用的类型是SimpleTrigger和CronTrigger。

          SimpleTrigger适用于一次性的任务执行（在给定的时间段只执行一次的作业任务），或者你需要在指定时间多次触发作业任务，每次触发都延迟固定的时间。CronTrigger适用于基于类似日历时间表的触发，比如“每个周五的下午”或是“每月10号的10:15”。

        为什么要分别定义作业任务和触发器？许多作业调度并没有区分作业任务和触发器的概念。有些框架把作业任务简单定义成执行时间（或计划）以及一些小作业标识符，其他框架更像是整合了Quartz框架的作业和触发器对象。因此我们设计Quartz时，我们决定构建调度器时拆分开调度和任务是有意义的，在我看来，这样做还是有许多好处。

        例如，作业任务可以独立于触发器在作业调度中创建和存储，多个触发器可以关联到相同的作业任务中。另一个好处是在作业任务关联的触发器失效后，仍然能够在调度器上松耦合地配置作业任务，因此该作业不需要重新定义，一段时间后能够重新调度。它还允许你在不重新实例化关联的作业任务下修改和替换触发器。

 

Identites（标识符）

        作业任务和触发器被注册到Quartz调度器时需要提供标识信息。这种标识信息（也称作作业任务键和触发器键）允许作业任务和触发器按组存放，这样可以很方便地将你的作业任务和触发器分组，比如分为“报表类Job”和“维护类Job”。作业任务和触发器的键的名称部分在同一个组内必须唯一，换句话说，作业任务和触发器的键（或标识符）的名字是由键名和组名共同组成的。

    现在你对作业任务和触发器有一个大概的了解了，你可以在“第三课 更多关于Jobs和JobDetails”和“第四课 更多关于Triggers”学到更多关于它们的知识。