Quartz Job Scheduling Framework［翻译］第三章. Hello Quartz (二)

3. 声明式部署一个 Job

前面我们讨论过，尽可能的用声明式处理软件配置，其次才才虑编程式。再来看代码  3.6，如果我们要在 job 启动之后改变它的执行时间和频度，必须去修改源代码重新编译。这种方式只适用于小的例子程序，但是对于一个大且复杂的系统，这就成了一个问题了。因此，假如能以声明式部署 Quart Job 时，并且也是需求允许的情况下，你应该每次都选择这种方式。

·配置 quartz.properties 文件

文件 quartz.properties 定义了 Quartz 应用运行时行为，还包含了许多能控制 Quartz 运转的属性。本章只会讲到它的基本配置；更多的高级设置将在以后讨论。在现阶段也不用太深入到每一项配置有效值的细节。

现在我们来看看最基础的 quartz.properties 文件，并讨论其中一些设置。代码 3.7 是一个修剪版的 quartz.propertis 文件。

注
Quartz 框架会为几乎所有的这些属性设定默认值。

代码 3.7. 基本的 Quartz Properties 文件


#===============================================================  
#Configure Main Scheduler Properties  
#===============================================================   
org.quartz.scheduler.instanceName = QuartzScheduler   
org.quartz.scheduler.instanceId = AUTO  

#===============================================================  
#Configure ThreadPool  
#===============================================================   
org.quartz.threadPool.threadCount =  5   
org.quartz.threadPool.threadPriority = 5   
org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool  

#===============================================================  
#Configure JobStore  
#===============================================================   
org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore  

#===============================================================  
#Configure Plugins  
#===============================================================   
org.quartz.plugin.jobInitializer.class =   
org.quartz.plugins.xml.JobInitializationPlugin   
  
org.quartz.plugin.jobInitializer.overWriteExistingJobs = true  
org.quartz.plugin.jobInitializer.failOnFileNotFound = true  
org.quartz.plugin.jobInitializer.validating=false  

在代码 3.7 所示的 quartz.properties 文件中，属性被逻辑上分为了四部分。属性在写法上无须要求分组或按特定的顺序。有 # 的行是注释行。

注
这里讨论的并没有涉及到所有可能的设置，仅仅是一些基本的设置。也是你需要去熟悉的，能使声明式例子运转起来的必须的设置项。quartz.properties 中的所有属性配置将会分散在本书中的各章节中依据所在章节涉及内容详细讨论。

·调度器属性

第一部分有两行，分别设置调度器的实例名(instanceName) 和实例 ID (instanceId)。属性 org.quartz.scheduler.instanceName 可以是你喜欢的任何字符串。它用来在用到多个调度器区分特定的调度器实例。多个调度器通常用在集群环境中。(Quartz 集群将会在第十一章，“Quartz 集群”中讨论)。现在的话，设置如下的一个字符串就行：

org.quartz.scheduler.instanceName = QuartzScheduler

实际上，这也是当你没有该属性配置时的默认值。

代码 3.7 中显示的调度器的第二个属性是 org.quartz.scheduler.instanceId。和 instaneName 属性一样，instanceId 属性也允许任何字符串。这个值必须是在所有调度器实例中是唯一的，尤其是在一个集群当中。假如你想 Quartz 帮你生成这个值的话，可以设置为 AUTO。如果 Quartz 框架是运行在非集群环境中，那么自动产生的值将会是 NON_CLUSTERED。假如是在集群环境下使用 Quartz，这个值将会是主机名加上当前的日期和时间。大多情况下，设置为 AUTO 即可。

·线程池属性

接下来的部分是设置有关线程必要的属性值，这些线程在 Quartz 中是运行在后台担当重任的。threadCount 属性控制了多少个工作者线程被创建用来处理 Job。原则上是，要处理的 Job 越多，那么需要的工作者线程也就越多。threadCount 的数值至少为 1。Quartz 没有限定你设置工作者线程的最大值，但是在多数机器上设置该值超过100的话就会显得相当不实用了，特别是在你的 Job 执行时间较长的情况下。这项没有默认值，所以你必须为这个属性设定一个值。

threadPriority 属性设置工作者线程的优先级。优先级别高的线程比级别低的线程更优先得到执行。threadPriority 属性的最大值是常量 java.lang.Thread.MAX_PRIORITY，等于10。最小值为常量 java.lang.Thread.MIN_PRIORITY，为1。这个属性的正常值是 Thread.NORM_PRIORITY，为5。大多情况下，把它设置为5，这也是没指定该属性的默认值。

最后一个要设置的线程池属性是 org.quartz.threadPool.class。这个值是一个实现了 org.quartz.spi.ThreadPool 接口的类的全限名称。Quartz 自带的线程池实现类是 org.quartz.smpl.SimpleThreadPool，它能够满足大多数用户的需求。这个线程池实现具备简单的行为，并经很好的测试过。它在调度器的生命周期中提供固定大小的线程池。你能根据需求创建自己的线程池实现，如果你想要一个随需可伸缩的线程池时也许需要这么做。这个属性没有默认值，你必须为其指定值。

·作业存储设置

作业存储部分的设置描述了在调度器实例的生命周期中，Job 和 Trigger 信息是如何被存储的。我们还没有谈论到作业存储和它的目的；因为对当前例子是非必的，所以我们留待以后说明。现在的话，你所要了解的就是我们存储调度器信息在内存中而不是在关系型数据库中就行了。

把调度器信息存储在内存中非常的快也易于配置。当调度器进程一旦被终止，所有的 Job 和 Trigger 的状态就丢失了。要使 Job 存储在内存中需通过设置  org.quartz.jobStrore.class 属性为 org.quartz.simpl.RAMJobStore，就像在代码 3.7 所做的那样。假如我们不希望在 JVM 退出之后丢失调度器的状态信息的话，我们可以使用关系型数据库来存储这些信息。这需要另一个作业存储(JobStore) 实现，我们在后面将会讨论到。第五章“Cron Trigger 和其他”和第六章“作业存储和持久化”会提到你需要用到的不同类型的作业存储实现。

·插件配置

在这个简单的 quartz.properties 文件中最后一部分是你要用到的 Quart 插件的配置。插件常常在别的开源框架上使用到，比如 Apache 的 Struts 框架(见 http://struts.apache.org)。

一个声明式扩框架的方法就是通过新加实现了 org.quartz.spi.SchedulerPlugin 接口的类。SchedulerPlugin  接口中有给调度器调用的三个方法。

注
Quartz 插件会在第八章“使用 Quartz 插件”中详细讨论

要在我们的例子中声明式配置调度器信息，我们会用到一个 Quartz 自带的叫做 org.quartz.plugins.xml.JobInitializationPlugin 的插件。

默认时，这个插件会在 classpath 中搜索名为 quartz_jobs.xml 的文件并从中加载 Job 和 Trigger 信息。

在下一节中讨论 quartz_jobs.xml 文件，这是我们所参考的非正式的 Job 定义文件。

注
默认时，插件 JobInitializationPlugin 在 classpath 中寻找 quartz_jobs.xml 文件。你可以覆盖相应设置强制这个插件使用不同的文件名查找。要做到这个，你必须设置上一节讨论的 quartz.properties 中的文件名。目前，我们就使用默认的文件名 quartz_jobs.xml，至于如何修改 quartz.properties 中相应设置会在本章中后面讲到。

·使用 quartz_jobx.xml 文件

代码 3.8 就是目录扫描例子的 Job 定义的 XML 文件。正如代码 3.5 所示例子那样，这里我们用的是声明式途径来配置 Job 和 Trigger 信息的。

代码 3.8. ScanDirectory Job 的 quartz_jobs.xml

<?xml version='1.0' encoding='utf-8'?>  
  
<quartz>  
  
  <job>  
    <job-detail>  
     <name>ScanDirectory</name>  
     <group>DEFAULT</group>  
     <description>  
          A job that scans a directory for files   
     </description>  
     <job-class>  
            org.cavaness.quartzbook.chapter3.ScanDirectoryJob   
     </job-class>  
     <volatility>false</volatility>  
     <durability>false</durability>  
     <recover>false</recover>  
     <job-data-map allows-transient-data="true">  
         <entry>  
         <key>SCAN_DIR</key>  
         <value>c:\quartz-book\input</value>  
       </entry>  
     </job-data-map>  
    </job-detail>  
  
    <trigger>  
     <simple>  
       <name>scanTrigger</name>  
       <group>DEFAULT</group>  
       <job-name>ScanDirectory</job-name>  
       <job-group>DEFAULT</job-group>  
       <start-time>2005-06-10 6:10:00 PM</start-time>  
       <!-- repeat indefinitely every 10 seconds -->  
       <repeat-count>-1</repeat-count>  
       <repeat-interval>10000</repeat-interval>  
     </simple>  
    </trigger>  
  
  </job>  
</quartz>  

<job> 元素描述了一个要注册到调度器上的 Job，相当于我们在前面章节中使用 scheduleJob() 方法那样。你所看到的<job-detail> 和  <trigger> 这两个元素就是我们在代码 3.5 中以编程式传递给方法 schedulerJob() 的参数。前面本质上是与这里一样的，只是现在用的是一种较流行声明的方式。你还可以对照着代码 3.5 中的例子来看在代码3.8 中我们是如何设置 SCAN_DIR 属性到 JobDataMap 中的。

<trigger>元素也是非常直观的：它使用前面同样的属性，但更简单的建立一个 SimpleTrigger。因此代码 3.8 仅仅是一种不同的(可论证的且更好的)方式做了代码 3.5 中同样的事情。显然，你也可以支持多个 Job。在代码3.6 中我们编程的方式那么做的，也能用声明的方式来支持。代码 3.9 显示了与代码 3.6 可比较的版本

代码 3.9. 你能在一个 quartz_jobs.xml 文件中指定多个 Job


<?xml version='1.0' encoding='utf-8'?>  
  
<quartz>  
  <job>  
    <job-detail>  
     <name>ScanDirectory1</name>  
     <group>DEFAULT</group>  
     <description>  
           A job that scans a directory for files   
     </description>  
     <job-class>  
           org.cavaness.quartzbook.chapter3.ScanDirectoryJob   
     </job-class>  
     <volatility>false</volatility>  
     <durability>false</durability>  
     <recover>false</recover>  
  
     <job-data-map allows-transient-data="true">  
     <entry>  
       <key>SCAN_DIR</key>  
         <value>c:\quartz-book\input1</value>  
     </entry>  
    </job-data-map>  
  </job-detail>  
  
  <trigger>  
    <simple>  
     <name>scanTrigger1</name>  
     <group>DEFAULT</group>  
     <job-name>ScanDirectory1</job-name>  
     <job-group>DEFAULT</job-group>  
     <start-time>2005-07-19 8:31:00 PM</start-time>  
     <!-- repeat indefinitely every 10 seconds -->  
     <repeat-count>-1</repeat-count>  
     <repeat-interval>10000</repeat-interval>  
    </simple>  
  </trigger>  
</job>  
  
<job>  
  <job-detail>  
    <name>ScanDirectory2</name>  
    <group>DEFAULT</group>  
    <description>  
          A job that scans a directory for files   
    </description>  
    <job-class>  
          org.cavaness.quartzbook.chapter3.ScanDirectoryJob   
    </job-class>  
    <volatility>false</volatility>  
    <durability>false</durability>  
    <recover>false</recover>  
  
    <job-data-map allows-transient-data="true">  
      <entry>  
       <key>SCAN_DIR</key>  
       <value>c:\quartz-book\input2</value>  
     </entry>  
    </job-data-map>  
  </job-detail>  
  
  <trigger>  
    <simple>  
     <name>scanTrigger2</name>  
     <group>DEFAULT</group>  
     <job-name>ScanDirectory2</job-name>  
     <job-group>DEFAULT</job-group>  
     <start-time>2005-06-10 6:10:00 PM</start-time>  
     <!-- repeat indefinitely every 15 seconds -->  
     <repeat-count>-1</repeat-count>  
     <repeat-interval>15000</repeat-interval>  
    </simple>  
  </trigger>  
</job>  
</quartz>  

·为插件修改 quartz.properties 配置

在本章前面，告诉过你的是，JobInitializationPlugin 找寻 quartz_jobs.xml 来获得声明的 Job 信息。假如你想改变这个文件名，你需要修改 quartz.properties 来告诉插件去加载那个文件。例如，假如你想要 Quartz 从名为 my_quartz_jobs.xml 的 XML 文件中加载 Job 信息，你不得不为插件指定这一文件名。代码 3.10 显示了怎么完成这个配置；我们现在是最后一次在这里重复说明这一插件部分。

代码 3.10. 为 JobInitializationPlugin 修改 quartz.properties


org.quartz.plugin.jobInitializer.class = org.quartz.plugins.xml.JobInitializationPlugin   

org.quartz.plugin.jobInitializer.fileName = my_quartz_jobs.xml   
  
org.quartz.plugin.jobInitializer.overWriteExistingJobs = true  
org.quartz.plugin.jobInitializer.validating = false  
org.quartz.plugin.jobInitializer.overWriteExistingJobs = false  
org.quartz.plugin.jobInitializer.failOnFileNotFound = true  

在代码 3.10中，我们添加了属性 org.quartz.plugin.jobInitializer.fileName 并设置该属性值为我们想要的文件名。这个文件名要对 classloader 可见，也就是说要在 classpath 下。

当 Quartz 启动后读取 quartz.properties 文件，然后初始化插件。它会传递上面配置的所有属性给插件，这时候插件也就得到通知去搜寻不同的文件。

译者后记：
想了又想，关于动词的 “Schedule” 还是选择“部署”，此前用的是“安排”，感觉不那么正式。当然英语中“部署”基本都用“Deploy”对应，平时与同事交流 Quartz 方面的技术都是说“往调度器上部署一个 Job”的，只要词能达意就行。

对于 “register with the Scheduler”，有时候是用的“通过调度器来注册”，有时候是“注册到调度器上”，意思基本一致的。



4. 打包 Quartz 应用程序

让我们最后简单讨论打包一个用到了 Quarts 框架的应用程序的流程，也以此来结束本章的内容。

·Quartz 第三方依赖包

从 1.5 版的发行包开始，你会看到一个 <QUARTZ_HOME>\lib 目录，在这个目录，你会发现几个子目录：

·<QUARTZ_HOME>\lib\core
·<QUARTZ_HOME>\lib\optional
·<QUARTZ_HOME>\lib\build

作为开发呢，你绝对是需求 Quartz JAR 包，也需要其他一些依赖包。需要哪些第三方包还依赖于你是运行在独立环境中还是作为一个 J2EE 发行包的一部份。典型的，jakarta Commons 库 (commons-loggin, commons-beanutils，还有其他的) 总是要用到。然而，当你是部署到一个应用服务器环境中，你需要确保不能把那些在应用服务器上已存在的包拷过去；如果你这样做的，你可能回得到非常奇怪的结果。

表 3.1 列出了第三方包的信息，帮助你确定是否需要在应用中包含它们


表 3.1. Quartz  第三方包，必须/可选

名称 必须/备注 网址

activation.jar 主要是 JavaMail 要用到 http://java.sun.com/products/javabeans/glasgow/jaf.html

commons-beanutils.jar 是 http://jakarta.apache.org/commons/beanutils

commons-collections.jar 是 http://jakarta.apache.org/commons/collections

commons-dbcp-1.1.jar 是，假如用到数据库作为作业存储 http://jakarta.apache.org/commons/dbcp

commons-digester.jar 是 假如你使用了某些插件，就需要它

commons-logging.jar 是 http://jakarta.apache.org/commons/logging/

commons-pool-1.1.jar  http://jakarta.apache.org/commons/pool/

javamail.jar 发送 e-mail 用 http://java.sun.com/products/javamail/

jdbc2_0-stdext.jar 是，假如用到数据库作为作业存储 http://java.sun.com/products/jdbc/

jta.jar 是，假如用到数据库作为作业存储 http://java.sun.com/products/jta/database

quartz.jar 是 Quart 框架核心包

servlet.jar 假如使用了Servlet 容器，但容器中应该存在 http://java.sun.com/products/servlet/

log4j.jar 来吧，谁没用过它呢？ http://logging.apache.org/



·配置和属性文件

你还必须在你的应用中包含 quartz.properties。假如你是应散装(exploded format) 形式部署应用，你应该把 quartz.properties 文件放置在类加载器能够加载的目录中。(所谓的 “exploed” 形式指不打成一个 JAR、WAR、EAR 或者其他 Java 包，以独立文件存在于文件系统中) 例如，如果你有一个 classes 目录(比如一个 Web 应用的 WEB-INF/classes 目录)，就可以把 quartz.properties 文件放在那儿。假如你以 Java 打包形式部署，应该放属性文件放在包的根下。在对待 quartz_job.xml 文件时也使用同样的规则。