[译]Quartz 2.2.x 第三课 更多关于Jobs和JobDetails

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

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

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

import static org.quartz.JobBuilder.*;

我们先再看一下第一课中展示的代码片段，来分析一下Job的本质以及生命周期。

  // 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);

Job接口的实现类HelloJob可以这样定义

  public class HelloJob implements Job {

    public HelloJob() {
    }

    public void execute(JobExecutionContext context)
      throws JobExecutionException
    {
      System.err.println("Hello!  HelloJob is executing.");
    }
  }

请注意我们给调度器提供了一个JobDetail实例对象，我们构建JobDetail对象时仅提供了job的class对象，调度器就知道它要执行job类型。每次调度器执行job时，它在调用excecute方法前会创建一个新的job实例。当调用完成后，关联的job对象实例会被释放，释放的实例会被垃圾回收机制回收。这种调用过程导致的其中一个结果是jobs对象必须要有一个无参数构造器（使用默认的JobFactory实现时），另外一个结果jobs实现类不能定义状态数据字段，因为这些状态数据字段在调用job任务时不会被保留。

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

JobDataMap

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

下面的代码片段演示了在定义/构建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 Developer Connection技术贴中找到：Serialization in the real world。当然，你可以选择将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中取值。你可以自主选择编写代码的方式。

Job "Instances"

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

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

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

当触发器被触发时，相关的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”术语。

Job状态和并发机制

现在介绍一些关于Job状态值和并发的额外信息。有一对加在Job类上面的注解，可以影响Quartz框架的这些方面的行为。

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

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

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

Jobs的其它属性

 

接下来浏览Job实例的其它属性，这些属性是通过JobDetail对象传递给Job实例的。

        Durability-如果一个Job是非持久化的，一旦没有任何活跃的触发器关联这个Job实例时，这个实例会自动地从调度器中移除。换句话说，非持久化的jobs的生命周期是以存在的触发器为界限的。

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

 

JobExecutioinException

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