TriggerBuilder详解

TriggerBuilder是⽤来创建触发器Trigger的。它与JobBuilder在整体结构或者说设计风格上可以说是⼀模⼀样的，同样采⽤Builder模式。

以下为TriggerBuilder类中的api说明：

1、TriggerBuilder.newTrigger()

调用自己的无参构造方法，创建⼀个新的TriggerBuilder，⽤它来定义触发器的规范。

源码：

/**
     * Create a new TriggerBuilder with which to define a 
     * specification（规范） for a Trigger.
     * 
     * @return the new TriggerBuilder
     */
    public static TriggerBuilder<Trigger> newTrigger() {
        return new TriggerBuilder<Trigger>();
    }
    

2、TriggerBuilder.withIdentity()

        TriggerBuilder和JobBuilder的withIdentity()⽅法⾮常⾮常的相似，甚⾄这两篇⽂章也⾮常相似。它们区别是：

        TriggerBuilder⽣成Trigger的唯⼀标识TriggerKey，暂时保存在TriggerBuilder中；

        JobBuilder是⽣成JobDetail的唯⼀标识JobKey，暂时保存在JobBuilder中。

     /**

       使用给定的名称和默认组创建唯一的TriggerKey,标识该Trigger。
     * Use a <code>TriggerKey</code> with the given name and default group to
     * identify the Trigger.
     * 
     * <p>If none of the 'withIdentity' methods are set on the TriggerBuilder,
     * then a random, unique TriggerKey will be generated.</p>
     * 
     * @param name the name element for the Trigger's TriggerKey
     * @return the updated TriggerBuilder
     * @see TriggerKey
     * @see Trigger#getKey()
     */
    public TriggerBuilder<T> withIdentity(String name) {
        key = new TriggerKey(name, null);
        return this;
    }  
    
    /**
        使用给定的名称和组 创建唯一的TriggerKey,标识该Trigger。
     * Use a TriggerKey with the given name and group to
     * identify the Trigger.
     * 
     * <p>If none of the 'withIdentity' methods are set on the TriggerBuilder,
     * then a random, unique TriggerKey will be generated.</p>
     * 
     * @param name the name element for the Trigger's TriggerKey
     * @param group the group element for the Trigger's TriggerKey
     * @return the updated TriggerBuilder
     * @see TriggerKey
     * @see Trigger#getKey()
     */
    public TriggerBuilder<T> withIdentity(String name, String group) {
        key = new TriggerKey(name, group);
        return this;
    }
    
    /**
       使用给定的TriggerKey 标识该Trigger
     * Use the given TriggerKey to identify the Trigger.  
     * 
     * <p>If none of the 'withIdentity' methods are set on the TriggerBuilder,
     * then a random, unique TriggerKey will be generated.</p>
     * 
     * @param triggerKey the TriggerKey for the Trigger to be built
     * @return the updated TriggerBuilder
     * @see TriggerKey
     * @see Trigger#getKey()
     */
    public TriggerBuilder<T> withIdentity(TriggerKey triggerKey) {
        this.key = triggerKey;
        return this;
    }

3、TriggerKey

        JobKey和TriggerKey真的可以说是⼀模⼀样，它们都Key的⼦类。除了参数名其他都⼀模⼀样，只不过⼀个⽤来标识JobDetail，⼀个⽤来标识Trigger。

public final class TriggerKey extends Key<TriggerKey> {
  
    private static final long serialVersionUID = 8070357886703449660L;

    public TriggerKey(String name) {
        super(name, null);
    }

    public TriggerKey(String name, String group) {
        super(name, group);
    }

    public static TriggerKey triggerKey(String name) {
        return new TriggerKey(name, null);
    }
    
    public static TriggerKey triggerKey(String name, String group) {
        return new TriggerKey(name, group);
    }
    
}

4、TriggerBuilder.startNow()

        Trigger从当前时刻开始执⾏。与startNow相似功能的⽅法还有startAt()，endAt()。

 唯⼀需要注意的是：

        当调⽤startAt()⽅法时传⼊的时间早于cron表达式设置的时间，则将会触发⼀次，但不管cron表达式是否会多次执⾏，都只会触发⼀次。

        例如，cron表达式为：0 0 12 * * ？，即每天12点执⾏⼀次，⽽startAt设置的时间是三天前，那么创建定时任务后只会触发⼀次，⽽不是三次。

    /**
     * Set the time the Trigger should start at to the current moment - 
     * the trigger may or may not fire at this time - depending upon the 
     * schedule configured for the Trigger.  
     * 
     * @return the updated TriggerBuilder
     * @see Trigger#getStartTime()
     */
    public TriggerBuilder<T> startNow() {
        this.startTime = new Date();
        return this;
    }

    /**
        设置触发器从入参的triggerStartTime时间开始执行。

     * Set the time the Trigger should start at - the trigger may or may
     * not fire at this time - depending upon the schedule configured for
     * the Trigger.  However the Trigger will NOT fire before this time,
     * regardless of the Trigger's schedule.
     *  
     * @param triggerStartTime the start time for the Trigger.
     * @return the updated TriggerBuilder
     * @see Trigger#getStartTime()
     * @see DateBuilder
     */
    public TriggerBuilder<T> startAt(Date triggerStartTime) {
        this.startTime = triggerStartTime;
        return this;
    }

     /**
        设置触发器从入参的triggerEndTime时间结束执行。

     * Set the time at which the Trigger will no longer fire - even if it's
     * schedule has remaining repeats.    
     *  
     * @param triggerEndTime the end time for the Trigger.  If null, the end time is indefinite.
     * @return the updated TriggerBuilder
     * @see Trigger#getEndTime()
     * @see DateBuilder
     */
    public TriggerBuilder<T> endAt(Date triggerEndTime) {
        this.endTime = triggerEndTime;
        return this;
    }

代码示例：

// Trigger立即触发
TriggerBuilder.newTrigger().startNow().build();

// Trigger指定时间触发
TriggerBuilder.newTrigger().startAt(time).build();

// Trigger指定周期时间触发，即corn方式
TriggerBuilder.newTrigger().startNow().endAt(endTime)
                        .withSchedule(dailyAtHourAndMinute(start.getHours(), start.getMinutes()))
                        .build();

 

5、TriggerBuilder.withSchedule()

        这个⽅法⽤于设置ScheduleBuilder，⽽ScheduleBuilder在负责真正实例化出⼀个Trigger。之所以这么做是因为ScheduleBuilder接⼝有四个实现类（如下图），我们需要哪种Trigger，那么withSchedule中就传⼊哪种Trigger对应的ScheduleBuilder。

CronScheduleBuilder可以创建⼀个基于Cron表达式的Trigger，这也是使⽤最多、功能最强⼤的Trigger。 如：CronScheduleBuilder.cronSchedule(cron)

CronScheduleBuilder类之cronSchedule：

/**
     * Create a CronScheduleBuilder with the given cron-expression string -
     * which is presumed to be a valid cron expression (and hence only a
     * RuntimeException will be thrown if it is not).
     * 
     * @param cronExpression
     *            the cron expression string to base the schedule on.
     * @return the new CronScheduleBuilder
     * @throws RuntimeException
     *             wrapping a ParseException if the expression is invalid
     * @see CronExpression
     */
    public static CronScheduleBuilder cronSchedule(String cronExpression) {
        try {
            return cronSchedule(new CronExpression(cronExpression));
        } catch (ParseException e) {
            // all methods of construction ensure the expression is valid by
            // this point...
            throw new RuntimeException("CronExpression '" + cronExpression
                    + "' is invalid.", e);
        }
    }

 TriggerBuilder类之withSchedule：

 /**
     * Set the {@link ScheduleBuilder} that will be used to define the 
     * Trigger's schedule.
     * 
     * <p>The particular <code>SchedulerBuilder</code> used will dictate
     * the concrete type of Trigger that is produced by the TriggerBuilder.</p>
     * 
     * @param schedBuilder the SchedulerBuilder to use.
     * @return the updated TriggerBuilder
     * @see ScheduleBuilder
     * @see SimpleScheduleBuilder
     * @see CronScheduleBuilder
     * @see CalendarIntervalScheduleBuilder
     */
    @SuppressWarnings("unchecked")
    public <SBT extends T> TriggerBuilder<SBT> withSchedule(ScheduleBuilder<SBT> schedBuilder) {
        this.scheduleBuilder = schedBuilder;
        return (TriggerBuilder<SBT>) this;
    }

6、TriggerBuilder.build()

        build⽅法使⽤withSchedule()⽅法设置的ScheduleBuilder实例化⼀个MutableTrigger。上⾯我们说ScheduleBuilder有四个实现类，那⾃然会产⽣四种Trigger（如下图），⽽这四个Trigger都是MutableTrigger的⼦类。其实这⾥就是多态⽽已。⽗类的引⽤指向⼦类的⽰例。

 /**
     * Produce the <code>Trigger</code>.
     * 
     * @return a Trigger that meets the specifications of the builder.
     */
    @SuppressWarnings("unchecked")
    public T build() {

        if(scheduleBuilder == null)
            scheduleBuilder = SimpleScheduleBuilder.simpleSchedule();
        MutableTrigger trig = scheduleBuilder.build();
        
        trig.setCalendarName(calendarName);
        trig.setDescription(description);
        trig.setStartTime(startTime);
        trig.setEndTime(endTime);
        if(key == null)
            key = new TriggerKey(Key.createUniqueName(null), null);
        trig.setKey(key); 
        if(jobKey != null)
            trig.setJobKey(jobKey);
        trig.setPriority(priority);
        
        if(!jobDataMap.isEmpty())
            trig.setJobDataMap(jobDataMap);
        
        return (T) trig;
    }