Quartz教程 第3课 Job和JobDetail详解

第3课 Job和JobDetail详解

正如你在第二课中看到的，Job接口非常容易实现，它只有一个execute方法。我们需要再学习一些知识去理解job的本质，Job接口的execute方法以及JobDetail接口。

当你实现Job接口类，Quartz需要你提供job实例的各种参数，Job接口实现类中的代码才知道如何去完成指定类型Job的实际工作。这个过程是通过JobDetail类来完成的，该类会在上一个章节简单的提到过。

JobDetail的实例是调用JobBuilder类创建的。通常你可以使用静态导入方式获得该类所有方法的调用，这样可以在你的代码体验DSL的感觉。

import static org.quartz.JobBuilder.*;

让我们花一些时间来讨论一下Quartz中Job以及Job实例的生命周期。首先，我们来回顾一下第1课中看到的代码片段：

  // 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的class对象，调度器就知道它要执行的job类型。每次调度器执行job时，它在调用excecute方法前会创建一个新的job实例。当执行完成时，job类实例的引用就会被丢弃，这个实例就会垃圾回收机制回收。这种调用过程导致的其中一个结果是job对象必须要有一个无参数构造器（使用默认的JobFacotry实现时），另外一个结果job实现类不能定义状态数据字段，因为这些状态数据字段的值在调用job任务时不会被保留。

你现在可能想问“我要怎样才能为Job实例提供配置参数？在执行任务时我要如何跟踪job对象的状态？”这两个问题的答案都一样：使用JobDataMap，它是JobDetail对象的一部分。

3.1 JobDataMap

JobDataMap可以用来持有任何可序列化的数据对象，当job实例对象被执行时这些参数对象会传递给它。JobDataMap实现Map接口，并且添加了一些非常方便的方法用来存取基本数据类型。

下面的代码片断演示了在定义/构建JobDetail对象时，job对象添加到调度器之前，如何将数据存放至JobDataMap中：

  // define the job and tie it to our DumbJob class

  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(将会在教程JobStore部分讨论)，你应该要多考虑放在JobDataMap中的数据对象，因为此时的对象会被序列化，因此这更容易出现版本问题。显然标准Java类型是很安全的，但是非标准Java类型，任何时候有人变更你序例化实例的类的定义，都要注意不要破坏兼容性。你可以选择将JDBC-JobStore和JobDataMap设计成只有基本数据类型和String类型才允许存储的map对象，从而从根本上消除序列化问题。

如果你在job类中添加setter方法，对应JobDataMap的键值（例如setJobSays(String val)方法对应上面例子里的jobSays数据），Quartz框架默认的JobFactory实现类在初始化job实例对象时会自动地调用这些setter方法，从而防止在调用执行方法时需要从map对象取指定的属性值。

触发器也可以关联JobDataMap对象，当存储在调度器中的job对象需要定期/重复执行，被多个触发器共用时，这种场景下使用JobDataMap将非常方便，然而每个独立的触发器，你都可以为job对象提供不同的输入参数。

在进行任务调度时JobDataMap存储在JobExecutionContext中非常方便获取。它合并了JobDetail和Trigger里的JobDataMap数据对象，后面的值会把前面相同键值的值覆盖。

接下来的例子演示了任务执行过程中从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注入map数据，它看起来可能是这样的：

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中取值。你可以自主选择编写代码的方式。

3.2 Job实例

许多用户对Job实例对象确切的结构是什么疑惑了很长时间，我们将尝试在这为大家解答，并且在下一个板块讲述Job状态和并发机制。

你可以创建一个单独的Job实现类，创建多个不同的JobDetail实例，将不同Job实例定义存储在调度器中，每个JobDetail实例都有各自的参数和JobDataMap，并且把这些JobDetail添加到调度器中。

例如：你创建一个Job接口的实现类，类名为“SalesReportJob”，Job类可以预先传入一些假想的参数（通过JobDataMap）来指定销售报表中业务员的名字。接下来创建多个Job的定义（即JobDetail），如“SalesReportForJoe”和 “SalesReportForMike”通过“Joe”和“Mike”指定到相应的JobDataMap中作为参数输入到各自的Job对象中。

当trigger被触发时，相关的JobDetail实例会被加载，通过在调度器中配置的JobFactory会将关联的Job类实例化。默认的JobFactory只是简单的调用Job类的newInstance方法，然后尝试调用匹配JobDataMap键值的setter方法。你可以开创建自己的JobFactory实现类，以完成一些诸如通过应用IOC或DI机制完成Job实例的创建和初始化的事情。

用Quartz框架的话来说，我们将每个存储的JobDetail称为Job定义或JobDetail实例，将每个执行的作业任务（Job）称为Job实例或Job定义实例。通常我们只用“job”单词来对应命名的Job定义或是JobDetail。当我们指Job接口的实现类时，一般使用“job class”术语。

3.3 Job状态和并发机制

现在，需要关注一下Job的状态数据（也叫JobDataMap）和并发机制。有一对加在Job类上面的注解，可以影响Quartz框架的这些方面的行为。

@DisallowConcurrentExecution注解添加到Job类中，会告知Quartz不要并发执行相同Job定义创建的多个实例对象。注意这里的措辞，要慎重地选择。引用上一章节的例子，如果SalesReportJob添加这个注解，在给定的时间段内只能执行一个 SalesReportJobForJoe实例对象，但是可以并发执行一个SalesReportJobForMike实例。这个限制是基于实例定义（JobDetail），而不是基于Job类实例。然而，在Quartz设计阶段决定在该类中携带注解，因为该注解会影响JobDetail类的编码。

@PersistJobDataAfterExecution注解添加到Job类中，会告知Quartz成功执行完execute方法后（没有抛出异常）更新JobDetail的JobDataMap中存储的数据。例如同一个JobDetail下一次执行时将接收更新后的值而不是初始值。跟@DisallowConcurrentExecution注解类似，@PersistJobDataAfterExecution注解适用于Job定义实例，而不是Job类实例。只是该注解是附着在Job类的成员变量中，因为它不会影响整个类的编码（例如statefulness只需要在execute方法代码内正确使用即可）。

如果你使用@PersistJobDataAfterExecution注解，强烈建议你也应该考虑使用 @DisallowConcurrentExecution注解，避免当两个相同JobDetail实例并发执行时可能由于最后存储状态数据不一致导致执行混乱。

3.4 其它的Job属性

这里总结了可以通过JobDetail对象为Job实例定义的其它属性。

Durability：如果一个Job是非持续的，一旦没有任何活跃的触发器关联这个Job实例时，这个实例会自动地从调度器中移除。换句话说，非持续的job的生命周期受限于触发器的存在性。

RequestsRecovery：如果一个Job设置了请求恢复参数，并且在调度器强制关闭过程中恰好在执行（强制关闭的情况例如：运行的线程崩溃，或者服务器宕机），当调度器重启时，它会重新被执行。这种情况下，JobExecutionContext的isRecovering方法会返回true。

3.5 JobExecutionException

最后，我们需要告知你Job.execute方法的一些细节。允许你从execute方法抛出的唯一一种异常类型是JobExecutionException（运行时异常除外，可以正常抛出），由于这个限制，你应该在execute方法内的try-catch代码块中包装好要处理的异常。你也可以花些时间查阅一下JobExecutionException的文档，便于你在开发Job类中需要捕获处理异常时，为调度器提供各种信息。