nthincludeddaytrigger.java

Quartz is a full-featured, open source job scheduling system that can be integrated with, or used al

     * Because of the conceptual design of <CODE>NthIncludedDayTrigger</CODE>,
     * it is not always possible to decide with certainty that the trigger
     * will <I>never</I> fire again. Therefore, it will search for the next 
     * fire time up to a given cutoff. These cutoffs can be changed by using the
     * {@link #setNextFireCutoffInterval(int)} and 
     * {@link #getNextFireCutoffInterval()} methods. The default cutoff is 12
     * of the intervals specified by <CODE>{@link #getIntervalType()
     * intervalType}</CODE>.
     * <P>
     * In most cases, the default value of this setting (12) is sufficient (it
     * is highly unlikely, for example, that you will need to look at more than
     * 12 months of dates to ensure that your trigger will never fire again).  
     * However, this setting is included to allow for the rare exceptions where
     * this might not be true.
     * <P>
     * For example, if your trigger is associated with a calendar that excludes
     * a great many dates in the next 12 months, and hardly any following that,
     * it is possible (if <CODE>n</CODE> is large enough) that you could run 
     * into this situation.  
     * 
     * @param nextFireCutoffInterval the desired cutoff interval
     * @see #getNextFireCutoffInterval()
     * @see #getNextFireTime()
     */
    public void setNextFireCutoffInterval(int nextFireCutoffInterval) {
        this.nextFireCutoffInterval = nextFireCutoffInterval;
    }
    
    /**
     * Returns the <CODE>nextFireCutoffInterval</CODE> for the 
     * <CODE>NthIncludedDayTrigger</CODE>.
     * <P>
     * Because of the conceptual design of <CODE>NthIncludedDayTrigger</CODE>,
     * it is not always possible to decide with certainty that the trigger
     * will <I>never</I> fire again. Therefore, it will search for the next 
     * fire time up to a given cutoff. These cutoffs can be changed by using the
     * {@link #setNextFireCutoffInterval(int)} and 
     * {@link #getNextFireCutoffInterval()} methods. The default cutoff is 12
     * of the intervals specified by <CODE>{@link #getIntervalType()
     * intervalType}</CODE>.
     * 
     * @return the chosen cutoff interval
     * @see #setNextFireCutoffInterval(int)
     * @see #getNextFireTime()
     */
    public int getNextFireCutoffInterval() {
        return this.nextFireCutoffInterval;
    }
    
    /** 
     * Sets the date/time on which the trigger may begin firing. This defines
     * the initial boundary for trigger firings &mdash; the trigger will not
     * fire prior to this date and time. Defaults to the current date and time
     * when the <CODE>NthIncludedDayTrigger</CODE> is created.
     * 
     * @param  startTime the initial boundary for trigger firings
     * @throws java.lang.IllegalArgumentException
     *         the specified start time is after the current end time or is 
     *         null
     * @see #getStartTime()
     */
    public void setStartTime(Date startTime) {
        if (startTime == null) {
            throw new IllegalArgumentException("Start time may not be null");
        }
        if ((this.endTime != null) && endTime.before(startTime)) {
            throw new IllegalArgumentException("Start time must be before end time.");
        }
        this.startTime = startTime;
    }

    /**
     * Returns the date/time on which the trigger may begin firing. This 
     * defines the initial boundary for trigger firings &mdash; the trigger
     * will not fire prior to this date and time.
     * 
     * @return the initial date/time on which the trigger may begin firing
     * @see #setStartTime(Date)
     */
    public Date getStartTime() {
        return this.startTime;
    }

    /** 
     * Sets the date/time on which the trigger must stop firing. This defines
     * the final boundary for trigger firings &mdash; the trigger will not
     * fire after to this date and time. If this value is null, no end time
     * boundary is assumed, and the trigger can continue indefinitely.
     * 
     * @param  endTime the final boundary for trigger firings
     * @throws java.lang.IllegalArgumentException
     *         the specified end time is before the current start time
     * @see #getEndTime()
     */
    public void setEndTime(Date endTime) {
        if ((endTime != null) && endTime.before(startTime)) {
            throw new IllegalArgumentException("End time must be after start time.");
        }
        this.endTime = endTime;
    }

    /** 
     * Returns the date/time on which the trigger must stop firing. This 
     * defines the final boundary for trigger firings &mdash; the trigger will
     * not fire after to this date and time. If this value is null, no end time
     * boundary is assumed, and the trigger can continue indefinitely.
     * 
     * @return the date/time on which the trigger must stop firing
     * @see #setEndTime(Date)
     */
    public Date getEndTime() {
        return this.endTime;
    }

    /**
     * Sets the time zone in which the <code>fireAtTime</code> will be resolved.
     * If no time zone is provided, then the default time zone will be used. 
     * 
     * @see TimeZone#getDefault()
     * @see #getTimeZone()
     * @see #getFireAtTime()
     * @see #setFireAtTime(String)
     */
    public void setTimeZone(TimeZone timeZone) {
        this.timeZone = timeZone;
    }
    
    /**
     * Gets the time zone in which the <code>fireAtTime</code> will be resolved.
     * If no time zone was explicitly set, then the default time zone is used. 
     * 
     * @see TimeZone#getDefault()
     * @see #getTimeZone()
     * @see #getFireAtTime()
     * @see #setFireAtTime(String)
     */
    public TimeZone getTimeZone() {
        if (timeZone == null) {
            timeZone = TimeZone.getDefault();
        }
        return timeZone;    
    }
    
    
    /**
     * Returns the next time at which the <CODE>NthIncludedDayTrigger</CODE>
     * will fire. If the trigger will not fire again, <CODE>null</CODE> will be
     * returned. 
     * <P>
     * Because of the conceptual design of <CODE>NthIncludedDayTrigger</CODE>,
     * it is not always possible to decide with certainty that the trigger
     * will <I>never</I> fire again. Therefore, it will search for the next 
     * fire time up to a given cutoff. These cutoffs can be changed by using the
     * {@link #setNextFireCutoffInterval(int)} and 
     * {@link #getNextFireCutoffInterval()} methods. The default cutoff is 12
     * of the intervals specified by <CODE>{@link #getIntervalType()
     * intervalType}</CODE>.
     * <P>
     * The returned value is not guaranteed to be valid until after
     * the trigger has been added to the scheduler.
     * 
     * @return the next fire time for the trigger
     * @see #getNextFireCutoffInterval()
     * @see #setNextFireCutoffInterval(int)
     * @see #getFireTimeAfter(Date)
     */
    public Date getNextFireTime() {
        return this.nextFireTime;
    }

    /**
     * Returns the previous time at which the 
     * <CODE>NthIncludedDayTrigger</CODE> fired. If the trigger has not yet 
     * fired, <CODE>null</CODE> will be returned.
     * 
     * @return the previous fire time for the trigger
     */
    public Date getPreviousFireTime() {
        return this.previousFireTime;
    }

    /**
     * Returns the first time the <CODE>NthIncludedDayTrigger</CODE> will fire
     * after the specified date. 
     * <P> 
     * Because of the conceptual design of <CODE>NthIncludedDayTrigger</CODE>,
     * it is not always possible to decide with certainty that the trigger
     * will <I>never</I> fire again. Therefore, it will search for the next 
     * fire time up to a given cutoff. These cutoffs can be changed by using the
     * {@link #setNextFireCutoffInterval(int)} and 
     * {@link #getNextFireCutoffInterval()} methods. The default cutoff is 12
     * of the intervals specified by <CODE>{@link #getIntervalType()
     * intervalType}</CODE>.
     * <P>
     * Therefore, for triggers with <CODE>intervalType = 
     * {@link NthIncludedDayTrigger#INTERVAL_TYPE_WEEKLY 
     * INTERVAL_TYPE_WEEKLY}</CODE>, if the trigger will not fire within 12
     * weeks after the given date/time, <CODE>null</CODE> will be returned. For
     * triggers with <CODE>intervalType = 
     * {@link NthIncludedDayTrigger#INTERVAL_TYPE_MONTHLY
     * INTERVAL_TYPE_MONTHLY}</CODE>, if the trigger will not fire within 12 
     * months after the given date/time, <CODE>null</CODE> will be returned. 
     * For triggers with <CODE>intervalType = 
     * {@link NthIncludedDayTrigger#INTERVAL_TYPE_YEARLY 
     * INTERVAL_TYPE_YEARLY}</CODE>, if the trigger will not fire within 12
     * years after the given date/time, <CODE>null</CODE> will be returned.  In 
     * all cases, if the trigger will not fire before <CODE>endTime</CODE>, 
     * <CODE>null</CODE> will be returned.
     * 
     * @param  afterTime The time after which to find the nearest fire time.
     *                   This argument is treated as exclusive &mdash; that is,
     *                   if afterTime is a valid fire time for the trigger, it
     *                   will not be returned as the next fire time.
     * @return the first time the trigger will fire following the specified
     *         date
     */
    public Date getFireTimeAfter(Date afterTime) {
        if (afterTime == null) {
            afterTime = new Date();
        }
        
        if (afterTime.before(this.startTime)) {
            afterTime = new Date(startTime.getTime() - 1000l);
        }
        
        if (this.intervalType == INTERVAL_TYPE_WEEKLY) {
            return getWeeklyFireTimeAfter(afterTime);
        } else if (this.intervalType == INTERVAL_TYPE_MONTHLY) {
            return getMonthlyFireTimeAfter(afterTime);
        } else if (this.intervalType == INTERVAL_TYPE_YEARLY) {
            return getYearlyFireTimeAfter(afterTime);
        } else {
            return null;
        }
    }

    /**
     * Returns the last time the <CODE>NthIncludedDayTrigger</CODE> will fire.
     * If the trigger will not fire at any point between <CODE>startTime</CODE>
     * and <CODE>endTime</CODE>, or there is not <code>endTime</code>, 
     * <CODE>null</CODE> will be returned.  
     * 
     * @return the last time the trigger will fire, or null if there is no
     * last time.
     */
    public Date getFinalFireTime() {
    	if(endTime == null)
    		return null;
    	
        Date finalTime = null;
        java.util.Calendar currCal = java.util.Calendar.getInstance();
        currCal.setTime(this.endTime);
        
        while ((finalTime == null) 
                && (this.startTime.before(currCal.getTime()))) {
            currCal.add(java.util.Calendar.DATE, -1);
            
            finalTime = getFireTimeAfter(currCal.getTime());
        }
        
        return finalTime;
    }

    /**
     * Called when the <CODE>Scheduler</CODE> has decided to 'fire' the trigger
     * (execute the associated <CODE>Job</CODE>), in order to give the 
     * <CODE>Trigger</CODE> a chance to update itself for its next triggering 
     * (if any).
     */
    public void triggered(Calendar calendar) {
        this.calendar = calendar;
        this.previousFireTime = this.nextFireTime;
        this.nextFireTime = getFireTimeAfter(this.nextFireTime);
    }
    
    /**
     * Called by the scheduler at the time a <CODE>Trigger</code> is first
     * added to the scheduler, in order to have the <CODE>Trigger</CODE>
     * compute its first fire time, based on any associated calendar.
     * <P>
     * After this method has been called, <CODE>getNextFireTime()</CODE>
     * should return a valid answer.
     * </p>
     * 
     * @return the first time at which the <CODE>Trigger</CODE> will be fired
     *         by the scheduler, which is also the same value 
     *         {@link #getNextFireTime()} will return (until after the first 
     *         firing of the <CODE>Trigger</CODE>).
     */
    public Date computeFirstFireTime(Calendar calendar) {       
        this.calendar = calendar;
        this.nextFireTime = 
            getFireTimeAfter(new Date(this.startTime.getTime() - 1000l));
        
        return this.nextFireTime;
    }

    /**
    * Called after the <CODE>Scheduler</CODE> has executed the 
    * <code>JobDetail</CODE> associated with the <CODE>Trigger</CODE> in order
    * to get the final instruction code from the trigger.
    * 
    * @param jobCtx the <CODE>JobExecutionContext</CODE> that was used by the
    *               <CODE>Job</CODE>'s <CODE>execute()</CODE> method.
    * @param result the <CODE>JobExecutionException</CODE> thrown by the
    *               <CODE>Job</CODE>, if any (may be <CODE>null</CODE>)
    * @return one of the Trigger.INSTRUCTION_XXX constants.
    */
    public int executionComplete(JobExecutionContext jobCtx,
        JobExecutionException result) {
        if (result != null && result.refireImmediately()) {
            return INSTRUCTION_RE_EXECUTE_JOB;
        }

        if (result != null && result.unscheduleFiringTrigger()) {
            return INSTRUCTION_SET_TRIGGER_COMPLETE;
        }
    
        if (result != null && result.unscheduleAllTriggers()) {
            return INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE;
        }
    
        if (!mayFireAgain()) {
            return INSTRUCTION_DELETE_TRIGGER;
        }
    
        return INSTRUCTION_NOOP;
    }

    /**
    * Used by the <CODE>Scheduler</CODE> to determine whether or not it is
    * possible for this <CODE>Trigger</CODE> to fire again.
    * <P>
    * If the returned value is <CODE>false</CODE> then the 
    * <CODE>Scheduler</CODE> may remove the <CODE>Trigger</CODE> from the
    * <CODE>JobStore</CODE>
    * 
    * @return a boolean indicator of whether the trigger could potentially fire
    *         again