Lesson 5: SimpleTrigger

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

SimpleTrigger should meet your scheduling needs if you need to have a job execute exactly once at a specific moment in time, or at a specific moment in time followed by repeats at a specific interval. For example, if you want the trigger to fire at exactly 11:23:54 AM on January 13, 2015, or if you want it to fire at that time, and then fire five more times, every ten seconds.

With this description, you may not find it surprising to find that the properties of a SimpleTrigger include: a start-time, and end-time, a repeat count, and a repeat interval. All of these properties are exactly what you’d expect them to be, with only a couple special notes related to the end-time property.

The repeat count can be zero, a positive integer, or the constant value SimpleTrigger.REPEAT_INDEFINITELY. The repeat interval property must be zero, or a positive long value, and represents a number of milliseconds. Note that a repeat interval of zero will cause ‘repeat count’ firings of the trigger to happen concurrently (or as close to concurrently as the scheduler can manage).

If you’re not already familiar with Quartz’s DateBuilder class, you may find it helpful for computing your trigger fire-times, depending on the startTime (or endTime) that you’re trying to create.

The endTime property (if it is specified) overrides the repeat count property. This can be useful if you wish to create a trigger such as one that fires every 10 seconds until a given moment in time - rather than having to compute the number of times it would repeat between the start-time and the end-time, you can simply specify the end-time and then use a repeat count of REPEAT_INDEFINITELY (you could even specify a repeat count of some huge number that is sure to be more than the number of times the trigger will actually fire before the end-time arrives).

如果你需要在一个指定时间段内执行一次作业任务或是在指定的时间间隔内多次执行作业任务，SimpleTrigger应该能满足你的调度需求。例如，你希望触发器在2015年1月13日上午11:23:54准时触发，或是希望在那个时间点触发，然后再重复触发5次，每隔10秒一次。

有了这样的描述，你就不会对SimpleTrigger包含的参数感到奇怪：开始执行时间，结束执行时间，重复次数和重复执行间隔时间。所有的参数都是你期望的那样，只是关于结束执行时间参数有两条特别的提示。

 重复次数可以为0，正整数或是SimpleTrigger.REPEAT_INDEFINITELY常量值。重复执行间隔必须为0或长整数（long类型），它表示毫秒数的值。注意如果重复执行间隔时间为0会导致数量为“重复次数”的触发器并发执行（或是在调度器控制下接近并发执行）。

    如果你还不熟悉Quartz的DateBuilder类，你尝试创建日期对象时会发现它非常方便地根据startTime或 endTime参数计算触发器的触发时间。

EndTime参数（如果被指定）会覆盖重复次数参数的效果。当你希望创建一个触发器，每隔10秒被触发一次直到给定的截止时间，而不是必须完成在给定的开始和结束时间段内的触发次数，使用endTime参数会非常方便，你可以仅仅指定一个end-time参数，并且将重复次数设置为REPEAT_INDEFINITELY（你甚至可以将重复次数指定为非常大的值，确保比结束执行时间到达前实际要执行的次数大就行）。

SimpleTrigger instances are built using TriggerBuilder (for the trigger’s main properties) and SimpleScheduleBuilder (for the SimpleTrigger-specific properties). To use these builders in a DSL-style, use static imports:

SimpleTrigger实例通过TriggerBuilder(for the trigger’s main properties)和SimpleScheduleBuilder(for the SimpleTrigger-specific properties)创建，通过如下代码导入他们的静态方法：

import static org.quartz.TriggerBuilder.*;
import static org.quartz.SimpleScheduleBuilder.*;
import static org.quartz.DateBuilder.*:

Here are various examples of defining triggers with simple schedules, read through them all, as they each show at least one new/different point:

下面是一些defining triggers with simple schedules的例子，可以从中比较他们的异同：

Build a trigger for a specific moment in time, with no repeats:

创建一个不会重复的在指定时间执行的trigger

SimpleTrigger trigger = (SimpleTrigger) newTrigger()
    .withIdentity("trigger1", "group1")
    .startAt(myStartTime) // some Date
    .forJob("job1", "group1") // identify job with name, group strings
    .build();

Build a trigger for a specific moment in time, then repeating every ten seconds ten times:

创建一个每10分钟执行一次、执行10次、在指定时间执行的trigger

trigger = newTrigger()
    .withIdentity("trigger3", "group1")
    .startAt(myTimeToStartFiring)  // if a start time is not given (if this line were omitted), "now" is implied
    .withSchedule(simpleSchedule()
        .withIntervalInSeconds(10)
        .withRepeatCount(10)) // note that 10 repeats will give a total of 11 firings
    .forJob(myJob) // identify job with handle to its JobDetail itself                   
    .build();

Build a trigger that will fire once, five minutes in the future:

创建一个5分钟后、只会执行一次的trigger

trigger = (SimpleTrigger) newTrigger()
    .withIdentity("trigger5", "group1")
    .startAt(futureDate(5, IntervalUnit.MINUTE)) // use DateBuilder to create a date in the future
    .forJob(myJobKey) // identify job with its JobKey
    .build();

Build a trigger that will fire now, then repeat every five minutes, until the hour 22:00:

创建一个立马执行的trigger, 每五分钟重复一次, 一直到 22:00:

trigger = newTrigger()
    .withIdentity("trigger7", "group1")
    .withSchedule(simpleSchedule()
        .withIntervalInMinutes(5)
        .repeatForever())
    .endAt(dateOf(22, 0, 0))
    .build();

Build a trigger that will fire at the top of the next hour, then repeat every 2 hours, forever:

创建一个trigger会在下一个小时的0分0秒执行，然后是一直是每两个小时执行一次

trigger = newTrigger()
    .withIdentity("trigger8") // because group is not specified, "trigger8" will be in the default group
    .startAt(evenHourDate(null)) // get the next even-hour (minutes and seconds zero ("00:00"))
    .withSchedule(simpleSchedule()
        .withIntervalInHours(2)
        .repeatForever())
    // note that in this example, 'forJob(..)' is not called
    //  - which is valid if the trigger is passed to the scheduler along with the job  
    .build();

    scheduler.scheduleJob(trigger, job);

Spend some time looking at all of the available methods in the language defined by TriggerBuilder and SimpleScheduleBuilder so that you can be familiar with options available to you that may not have been demonstrated in the examples above.

熟悉TriggerBuilder和SimpleScheduleBuilder定义的一些方法，还可以发现一些其他上面的例子中没有列举出来的选项。

Note that TriggerBuilder (and Quartz's other builders) will generally choose a reasonable value for properties that you do not explicitly set. For examples: if you don't call one of the *withIdentity(..)* methods, then TriggerBuilder will generate a random name for your trigger; if you don't call *startAt(..)* then the current time (immediately) is assumed.

另外， TriggerBuilder (以及quartz其他的builders) ,在你没有明确的为一些属性指定值的时候，builder会将其设置为一些有意义的值。比如没有设置 withIdentity() 方法的值时候， TriggerBuilder 会为你的trigger生成一个随机的名字；如果没有调用 startAt() 那默认就是当前的时间。

SimpleTrigger Misfire Instructions

SimpleTrigger has several instructions that can be used to inform Quartz what it should do when a misfire occurs. (Misfire situations were introduced in “Lesson 4: More About Triggers”). These instructions are defined as constants on SimpleTrigger itself (including JavaDoc describing their behavior). The instructions include:

Misfire Instruction Constants of SimpleTrigger

SimpleTrigger 有一些instructions 可以通知quartz在misfire 出现的时候告诉quartz应该做些什么。这些instructions在SimpleTrigger 有对应的常量定义(可以参阅JavaDoc文档)。这些instructions 包括：

SimpleTrigger中的Misfire Instruction 常量

MISFIRE_INSTRUCTION_IGNORE_MISFIRE_POLICY
MISFIRE_INSTRUCTION_FIRE_NOW
MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_EXISTING_REPEAT_COUNT
MISFIRE_INSTRUCTION_RESCHEDULE_NOW_WITH_REMAINING_REPEAT_COUNT
MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_REMAINING_COUNT
MISFIRE_INSTRUCTION_RESCHEDULE_NEXT_WITH_EXISTING_COUNT

You should recall from the earlier lessons that all triggers have the Trigger.MISFIRE_INSTRUCTION_SMART_POLICY instruction available for use, and this instruction is also the default for all trigger types.

If the ‘smart policy’ instruction is used, SimpleTrigger dynamically chooses between its various MISFIRE instructions, based on the configuration and state of the given SimpleTrigger instance. The JavaDoc for the SimpleTrigger.updateAfterMisfire() method explains the exact details of this dynamic behavior.

When building SimpleTriggers, you specify the misfire instruction as part of the simple schedule (via SimpleSchedulerBuilder):

在先前文章中使用的triggers都默认使用了Trigger.MISFIRE_INSTRUCTION_SMART_POLICY instruction, 这是默认的instruction对于所有的trigger类型来说。

如果smart policy instruciton被使用了，SimpleTrigger会基于configuration和SimpleTrigger instance的state动态的从各种MISFIRE instructions 中选取合适的。可以查看SimpleTrigger.updateAfterMisfire()的JavaDoc文档，详细描述了动态行为的细节。

通过SimpleSchedulerBuilder的simpleSchedule指定misfire instruction:

trigger = newTrigger()
    .withIdentity("trigger7", "group1")
    .withSchedule(simpleSchedule()
        .withIntervalInMinutes(5)
        .repeatForever()
        .withMisfireHandlingInstructionNextWithExistingCount())
    .build();