Home » quartz-1.6.0 » org » quartz » [javadoc | source]
org.quartz
public class: NthIncludedDayTrigger [javadoc | source]
java.lang.Object
   org.quartz.Trigger
      org.quartz.NthIncludedDayTrigger

All Implemented Interfaces:
    Cloneable, Serializable, Comparable

A trigger which fires on the Nth day of every interval type (#INTERVAL_TYPE_WEEKLY , #INTERVAL_TYPE_MONTHLY or #INTERVAL_TYPE_YEARLY ) that is not excluded by the associated calendar. When determining what the Nth day of the month or year is, NthIncludedDayTrigger will skip excluded days on the associated calendar. This would commonly be used in an Nth business day situation, in which the user wishes to fire a particular job on the Nth business day (i.e. the 5th business day of every month). Each NthIncludedDayTrigger also has an associated fireAtTime which indicates at what time of day the trigger is to fire.

All NthIncludedDayTriggers default to a monthly interval type (fires on the Nth day of every month) with N = 1 (first non-excluded day) and fireAtTime set to 12:00 PM (noon). These values can be changed using the #setN , #setIntervalType , and #setFireAtTime methods. Users may also want to note the #setNextFireCutoffInterval and #getNextFireCutoffInterval methods.

Take, for example, the following calendar:

July August September
Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1 W 1 2 3 4 5 W 1 2 W
W H 5 6 7 8 W W 8 9 10 11 12 W W H 6 7 8 9 W
W 11 12 13 14 15 W W 15 16 17 18 19 W W 12 13 14 15 16 W
W 18 19 20 21 22 W W 22 23 24 25 26 W W 19 20 21 22 23 W
W 25 26 27 28 29 W W 29 30 31 W 26 27 28 29 30
W

Where W's represent weekend days, and H's represent holidays, all of which are excluded on a calendar associated with an NthIncludedDayTrigger with n=5 and intervalType=INTERVAL_TYPE_MONTHLY. In this case, the trigger would fire on the 8th of July (because of the July 4 holiday), the 5th of August, and the 8th of September (because of Labor Day).

Field Summary
static final  long serialVersionUID     
public static final  int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW    Instructs the Scheduler that upon a mis-fire situation, the NthIncludedDayTrigger wants to be fired now by the Scheduler 
public static final  int MISFIRE_INSTRUCTION_DO_NOTHING    Instructs the Scheduler that upon a mis-fire situation, the NthIncludedDayTrigger wants to have nextFireTime updated to the next time in the schedule after the current time, but it does not want to be fired now. 
public static final  int INTERVAL_TYPE_MONTHLY    indicates a monthly trigger type (fires on the Nth included day of every month). 
public static final  int INTERVAL_TYPE_YEARLY    indicates a yearly trigger type (fires on the Nth included day of every year). 
public static final  int INTERVAL_TYPE_WEEKLY    indicates a weekly trigger type (fires on the Nth included day of every week). When using this interval type, care must be taken not to think of the value of n as an analog to java.util.Calendar.DAY_OF_WEEK. Such a comparison can only be drawn when there are no calendars associated with the trigger. To illustrate, consider an NthIncludedDayTrigger with n = 3 which is associated with a Calendar excluding non-weekdays. The trigger would fire on the 3rd included day of the week, which would be 4th actual day of the week. 
Fields inherited from org.quartz.Trigger:
INSTRUCTION_NOOP,  INSTRUCTION_RE_EXECUTE_JOB,  INSTRUCTION_SET_TRIGGER_COMPLETE,  INSTRUCTION_DELETE_TRIGGER,  INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE,  INSTRUCTION_SET_TRIGGER_ERROR,  INSTRUCTION_SET_ALL_JOB_TRIGGERS_ERROR,  MISFIRE_INSTRUCTION_SMART_POLICY,  STATE_NORMAL,  STATE_PAUSED,  STATE_COMPLETE,  STATE_ERROR,  STATE_BLOCKED,  STATE_NONE,  DEFAULT_PRIORITY
Constructor:
 public NthIncludedDayTrigger() 
 public NthIncludedDayTrigger(String name,
    String group) 
    Create an NthIncludedDayTrigger with the given name and group but no specified JobDetail. This will result initially in a default monthly trigger that fires on the first day of every month at 12:00 PM (n=1, intervalType=#INTERVAL_TYPE_MONTHLY , fireAtTime="12:00").

    Note that setJobName() and setJobGroup() must be called before the NthIncludedDayTrigger can be placed into a Scheduler.

    Parameters:
    name - the name for the NthIncludedDayTrigger
    group - the group for the NthIncludedDayTrigger
 public NthIncludedDayTrigger(String name,
    String group,
    String jobName,
    String jobGroup) 
    Create an NthIncludedDayTrigger with the given name and group and the specified JobDetail. This will result initially in a default monthly trigger that fires on the first day of every month at 12:00 PM (n=1, intervalType=#INTERVAL_TYPE_MONTHLY , fireAtTime="12:00").
    Parameters:
    name - the name for the NthIncludedDayTrigger
    group - the group for the NthIncludedDayTrigger
    jobName - the name of the job to associate with the NthIncludedDayTrigger
    jobGroup - the group containing the job to associate with the NthIncludedDayTrigger
Method from org.quartz.NthIncludedDayTrigger Summary:
computeFirstFireTime,   executionComplete,   getEndTime,   getFinalFireTime,   getFireAtTime,   getFireTimeAfter,   getIntervalType,   getN,   getNextFireCutoffInterval,   getNextFireTime,   getPreviousFireTime,   getStartTime,   getTimeZone,   mayFireAgain,   setEndTime,   setFireAtTime,   setIntervalType,   setN,   setNextFireCutoffInterval,   setStartTime,   setTimeZone,   triggered,   updateAfterMisfire,   updateWithNewCalendar,   validateMisfireInstruction
Methods from org.quartz.Trigger:
addTriggerListener,   clearAllTriggerListeners,   clone,   compareTo,   computeFirstFireTime,   equals,   executionComplete,   getCalendarName,   getDescription,   getEndTime,   getFinalFireTime,   getFireInstanceId,   getFireTimeAfter,   getFullJobName,   getFullName,   getGroup,   getJobDataMap,   getJobGroup,   getJobName,   getKey,   getMisfireInstruction,   getName,   getNextFireTime,   getPreviousFireTime,   getPriority,   getStartTime,   getTriggerListenerNames,   hashCode,   isVolatile,   mayFireAgain,   removeTriggerListener,   setCalendarName,   setDescription,   setEndTime,   setFireInstanceId,   setGroup,   setJobDataMap,   setJobGroup,   setJobName,   setMisfireInstruction,   setName,   setPriority,   setStartTime,   setVolatility,   toString,   triggered,   updateAfterMisfire,   updateWithNewCalendar,   validate,   validateMisfireInstruction
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.quartz.NthIncludedDayTrigger Detail:
 public Date computeFirstFireTime(Calendar calendar) 
    Called by the scheduler at the time a Trigger is first added to the scheduler, in order to have the Trigger compute its first fire time, based on any associated calendar.

    After this method has been called, getNextFireTime() should return a valid answer.

 public int executionComplete(JobExecutionContext jobCtx,
    JobExecutionException result) 
    Called after the Scheduler has executed the JobDetail associated with the Trigger in order to get the final instruction code from the trigger.
 public Date getEndTime() 
    Returns the date/time on which the trigger must stop firing. This defines the final boundary for trigger firings — 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.
 public Date getFinalFireTime() 
    Returns the last time the NthIncludedDayTrigger will fire. If the trigger will not fire at any point between startTime and endTime, null will be returned.
 public String getFireAtTime() 
    Returns the fire time for the NthIncludedDayTrigger as a string with the format "HH:MM", with HH representing the 24-hour clock hour of the fire time.
 public Date getFireTimeAfter(Date afterTime) 
    Returns the first time the NthIncludedDayTrigger will fire after the specified date.

    Because of the conceptual design of NthIncludedDayTrigger, it is not always possible to decide with certainty that the trigger will never fire again. Therefore, it will search for the next fire time up to a given cutoff. These cutoffs can be changed by using the #setNextFireCutoffInterval(int) and #getNextFireCutoffInterval() methods. The default cutoff is 12 of the intervals specified by intervalType .

    Therefore, for triggers with intervalType = INTERVAL_TYPE_WEEKLY , if the trigger will not fire within 12 weeks after the given date/time, null will be returned. For triggers with intervalType = INTERVAL_TYPE_MONTHLY , if the trigger will not fire within 12 months after the given date/time, null will be returned. For triggers with intervalType = INTERVAL_TYPE_YEARLY , if the trigger will not fire within 12 years after the given date/time, null will be returned. In all cases, if the trigger will not fire before endTime, null will be returned.

 public int getIntervalType() 
    Returns the interval type for the NthIncludedDayTrigger.
 public int getN() 
    Returns the day of the interval on which the NthIncludedDayTrigger should fire.
 public int getNextFireCutoffInterval() 
    Returns the nextFireCutoffInterval for the NthIncludedDayTrigger.

    Because of the conceptual design of NthIncludedDayTrigger, it is not always possible to decide with certainty that the trigger will never fire again. Therefore, it will search for the next fire time up to a given cutoff. These cutoffs can be changed by using the #setNextFireCutoffInterval(int) and #getNextFireCutoffInterval() methods. The default cutoff is 12 of the intervals specified by intervalType .

 public Date getNextFireTime() 
    Returns the next time at which the NthIncludedDayTrigger will fire. If the trigger will not fire again, null will be returned.

    Because of the conceptual design of NthIncludedDayTrigger, it is not always possible to decide with certainty that the trigger will never fire again. Therefore, it will search for the next fire time up to a given cutoff. These cutoffs can be changed by using the #setNextFireCutoffInterval(int) and #getNextFireCutoffInterval() methods. The default cutoff is 12 of the intervals specified by intervalType .

    The returned value is not guaranteed to be valid until after the trigger has been added to the scheduler.

 public Date getPreviousFireTime() 
    Returns the previous time at which the NthIncludedDayTrigger fired. If the trigger has not yet fired, null will be returned.
 public Date getStartTime() 
    Returns the date/time on which the trigger may begin firing. This defines the initial boundary for trigger firings — the trigger will not fire prior to this date and time.
 public TimeZone getTimeZone() 
    Gets the time zone in which the fireAtTime will be resolved. If no time zone was explicitly set, then the default time zone is used.
 public boolean mayFireAgain() 
    Used by the Scheduler to determine whether or not it is possible for this Trigger to fire again.

    If the returned value is false then the Scheduler may remove the Trigger from the JobStore

 public  void setEndTime(Date endTime) 
    Sets the date/time on which the trigger must stop firing. This defines the final boundary for trigger firings — 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.
 public  void setFireAtTime(String fireAtTime) 
    Sets the fire time for the NthIncludedDayTrigger, which should be represented as a string with the format "HH:MM[:SS]", with HH representing the 24-hour clock hour of the fire time. Hours can be represented as either a one-digit or two-digit number. Seconds are optional.
 public  void setIntervalType(int intervalType) 
 public  void setN(int n) 
    Sets the day of the interval on which the NthIncludedDayTrigger should fire. If the Nth day of the interval does not exist (i.e. the 32nd of a month), the trigger simply will never fire. N may not be less than 1.
 public  void setNextFireCutoffInterval(int nextFireCutoffInterval) 
    Sets the nextFireCutoffInterval for the NthIncludedDayTrigger.

    Because of the conceptual design of NthIncludedDayTrigger, it is not always possible to decide with certainty that the trigger will never fire again. Therefore, it will search for the next fire time up to a given cutoff. These cutoffs can be changed by using the #setNextFireCutoffInterval(int) and #getNextFireCutoffInterval() methods. The default cutoff is 12 of the intervals specified by intervalType .

    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.

    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 n is large enough) that you could run into this situation.

 public  void setStartTime(Date startTime) 
    Sets the date/time on which the trigger may begin firing. This defines the initial boundary for trigger firings — the trigger will not fire prior to this date and time. Defaults to the current date and time when the NthIncludedDayTrigger is created.
 public  void setTimeZone(TimeZone timeZone) 
    Sets the time zone in which the fireAtTime will be resolved. If no time zone is provided, then the default time zone will be used.
 public  void triggered(Calendar calendar) 
    Called when the Scheduler has decided to 'fire' the trigger (execute the associated Job), in order to give the Trigger a chance to update itself for its next triggering (if any).
 public  void updateAfterMisfire(Calendar calendar) 
    Updates the NthIncludedDayTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the NthIncludedDayTrigger was created

    If the misfire instruction is set to MISFIRE_INSTRUCTION_SMART_POLICY, then the instruction will be interpreted as #MISFIRE_INSTRUCTION_FIRE_ONCE_NOW .

 public  void updateWithNewCalendar(Calendar calendar,
    long misfireThreshold) 
    Updates the NthIncludedDayTrigger's state based on the given new version of the associated Calendar.
 protected boolean validateMisfireInstruction(int misfireInstruction) 
    Indicates whether misfireInstruction is a valid misfire instruction for this Trigger.