Quartz_2.2.X学习系列二：Tutorials - Lesson 2: The Quartz API, Jobs And Triggers

第二课小结：

Quartz API的关键接口如下：

Scheduler：这个是与Scheduler交互的主要API。

Job：这个是作业的接口类，当我们想创建一个让Scheduler执行任务的类时，需要实现这个接口类。

JobDetail: 用来定义Job实例的。

Trigger: 一个组件，它定义了一个给定作业将被执行的调度计划。

JobBuilder：用来定义/构造 JobDetail实例，它定义了Job对象的实例。

TriggerBuilder：用于定义/构造 Trigger实例。

 

Scheduler

它的生命周期由通过ScheduleFactory创建开始，到执行shutdown方法结束。

注：如果这个Scheduler没有执行Start()前，Scheduler并不会真正的对任何Triggers（执行Jobs）生效。

 

Builder静态类

Quartz提供了一些Builder类，这些Builder类使用了FI的流接口风格写法。更容易理解和编写。

import static org.quartz.JobBuilder.*;

JobDetail job = newJob(HelloJob.class)
      .withIdentity("myJob", "group1")
      .build();

 

Job接口只有一个方法execute，它有一个JobExecutionContext 对象，它提供了：

• Job实例：它包含了该Job的run-time环境信息
• scheduler：执行这个Job的scheduer的句柄
• Trigger: 触发这个execute的trigger句柄
• JobDetail：这个被执行Job的JobDetail对象。
• 其它项（见下面的源码）

它用于传递相关的信息给这个JOB实现类。

 

 

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：这个是作业的接口类，当我们想创建一个让Scheduler执行任务的类时，需要实现这个接口类。

JobDetail: 用来定义Job实例的。

Trigger: 一个组件，它定义了一个给定作业将被执行的调度计划。

JobBuilder：用来定义/构造 JobDetail实例，它定义了Job对象的实例。

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的生命周期由通过ScheduleFactory创建开始，到执行shutdown方法结束。

被创建出来的Scheduler接口可以被用于添加，移除，显示Jobs对象和Triggers对象，也可以执行其它关联Scheduler的操作，如暂停一个Trigger。

注：如果这个Scheduler没有执行Start()前，Scheduler并不会真正的对任何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（Domain Specific Language），有时也被引用为Fluent interface，在上节中，我们已经看到一个例子，这里我们再展示一部分。

 

FI简介：

在软件工程中，一个流接口（fluent Interface）是指实现一种实现面向对象的能提高代码可读性的API的方法。

一个FI通常用函数链来实现以完成一系列连续的操作内容调用，通常，操作内容有以下几个特点：

1.通过调用函数的返回值来定义

2.自身引用，新的内容和旧的一致

3.通过无效内容返回来终止调用

 

具体可以参考：

https://blog.csdn.net/hintcnuie/article/details/75127064

 

 // 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类引入的静态方法。同样的，构造Trigger的代码块使用了从TriggerBuilder类中引用的方法。

DSL的静态引入可以从使用下面这些语句实现：

 

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

 

上面不同的SchdeuleBuilder类的的方法用于定义不同类型的Schedules. DateBuilder类包含不同的方法，可以简单的为特别的时间点构造日期实例。 (如显示当前时间的下一个小时，如：现在是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:

Job是一个类，它实现了Job接口，这个接口只有一个简单的方法（execute），详见如下：

 

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触发（稍候会有更多的介绍），Job的execute(..)方法会被某个Scheduler的工作线程 调用。作为参数传到这个方法的JobExecutionContext 对象，它提供了：

• Job实例：它包含了该Job的run-time环境信息
• scheduler：执行这个Job的scheduer的句柄
• Trigger: 触发这个execute的trigger句柄
• JobDetail：这个被执行Job的JobDetail对象。
• 其它项（见下面的源码）

 

org.quartz.impl.JobExecutionContextImpl源代码（部分）：

可以看到这个被传入execute()方法中的参数对象包含了需要的基本信息：

• Schedular
• Trigger
• jobDetail
• Job
• jobDataMap：将JobDetail的Jobdata和Trigger的JobData都放入了其中

----------------------------------------------------------------

/**

     * <p>

     * Create a JobExcecutionContext with the given context data.

     * </p>

     */

    public JobExecutionContextImpl(Scheduler scheduler,

            TriggerFiredBundle firedBundle, Job job) {

        this.scheduler = scheduler;

        this.trigger = firedBundle.getTrigger();

        this.calendar = firedBundle.getCalendar();

        this.jobDetail = firedBundle.getJobDetail();

        this.job = job;

        this.recovering = firedBundle.isRecovering();

        this.fireTime = firedBundle.getFireTime();

        this.scheduledFireTime = firedBundle.getScheduledFireTime();

        this.prevFireTime = firedBundle.getPrevFireTime();

        this.nextFireTime = firedBundle.getNextFireTime();

       

        this.jobDataMap = new JobDataMap();

        this.jobDataMap.putAll(jobDetail.getJobDataMap());

        this.jobDataMap.putAll(trigger.getJobDataMap());

    }

----------------------------------------------------------------

 

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对象：在Job被添加到Scheduler的时候，被Quartz客户端（你的程序）创建。它包含为这个Job的多个属性设置，如：JobDataMap，它可以被用于为你的Job类实例存储状态信息。它是一个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对象：它被用于触发Jobs的执行。当你想计划一个JOB时，你可以实例化一个trigger，然后调整它的属性来实现你想要的计划。（比如：什么时候触发这个Job，什么时候结束）。

Trigger也有一个JobDataMap（跟JobDetail对象一样，有这个属性），对于传送一些参数给一个被该Trigger触发的Job中，是非常有用的。

Quartz有一些不同类型的trigger，但常用的类型只有两种， 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.”

 

SimpleTrigger:

适用于需要执行一次任务的触发，即在指定的时间中准时执行一次指定的JOB，它是非常方便的。

适用于需要在指定的时间中触发执行JOB，并可以重复执行N次这个JOB，中间可指定两次执行的时间离隔。

 

CronTrigger（项目中最常用）

适用于基于calendar时间的触发，如，每周五的中午，又如：每个月，第10天的10点15分，执行JOB。

 

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.

 

为什么是Jobs和Triggers呢？

许多任务计划并没有将Jobs和Triggers分开的概念。一些定义一个JOB为简单的执行时间（或计划），以及一些小的JOB标识符。另一些则很像是Quartz的Job和Trigger对象的结合。

在开发Quartz时，我们决定在调度计划和在该调度计划上执行的工作之间创建一个分离是有意义的。在我们看来，这样做有许多的优势的。

 

例如，可以在作业调度器中创建和存储作业，而不依赖于触发器，多个触发器可以与同一作业相关联。这种松耦合的另一个好处是，能够在相关触发器过期之后配置留在调度程序中的作业，这样就可以在以后重新安排它，而不必重新定义它。它还允许你修改或替换触发器，而不必重新定义与其相关联的作业。

 

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.

 

标识符

当作业和触发器被注册到Quartz调度计划时，它会被指定识别键。作业和触发器（JobKey和TriggerKey）的键允许它们被放置到“组”中，这对于组织你的作业和触发器到类别中（诸如“报告作业”和“维护作业”）是有用的。作业或触发器的键的名称部分必须在组内是惟一的——换句话说，作业或触发器的完整键（或标识符）是名称和组别的复合键。

 

 

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