org.quartz
Class NthIncludedDayTrigger

java.lang.Object
  extended by org.quartz.Trigger
      extended by org.quartz.NthIncludedDayTrigger
All Implemented Interfaces:
Serializable, Cloneable, Comparable

public class NthIncludedDayTrigger
extends Trigger

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(int), setIntervalType(int), and setFireAtTime(java.lang.String) methods. Users may also want to note the setNextFireCutoffInterval(int) 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).

Author:
Aaron Craven
See Also:
Serialized Form

Field Summary
static int INTERVAL_TYPE_MONTHLY
          indicates a monthly trigger type (fires on the Nth included day of every month).
static int INTERVAL_TYPE_WEEKLY
          indicates a weekly trigger type (fires on the Nth included day of every week).
static int INTERVAL_TYPE_YEARLY
          indicates a yearly trigger type (fires on the Nth included day of every year).
static 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.
static 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
 
Fields inherited from class org.quartz.Trigger
DEFAULT_PRIORITY, INSTRUCTION_DELETE_TRIGGER, INSTRUCTION_NOOP, INSTRUCTION_RE_EXECUTE_JOB, INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE, INSTRUCTION_SET_ALL_JOB_TRIGGERS_ERROR, INSTRUCTION_SET_TRIGGER_COMPLETE, INSTRUCTION_SET_TRIGGER_ERROR, MISFIRE_INSTRUCTION_SMART_POLICY, STATE_BLOCKED, STATE_COMPLETE, STATE_ERROR, STATE_NONE, STATE_NORMAL, STATE_PAUSED
 
Constructor Summary
NthIncludedDayTrigger()
          Create an NthIncludedDayTrigger with no specified name, group, or JobDetail.
NthIncludedDayTrigger(String name)
          Create an NthIncludedDayTrigger with the given name and default group but no specified JobDetail.
NthIncludedDayTrigger(String name, String group)
          Create an NthIncludedDayTrigger with the given name and group but no specified JobDetail.
NthIncludedDayTrigger(String name, String group, String jobName, String jobGroup)
          Create an NthIncludedDayTrigger with the given name and group and the specified JobDetail.
 
Method Summary
 Object clone()
           
 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.
 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.
 Date getEndTime()
          Returns the date/time on which the trigger must stop firing.
 Date getFinalFireTime()
          Returns the last time the NthIncludedDayTrigger will fire.
 String getFireAtTime()
          Returns the fire time for the NthIncludedDayTrigger as a string with the format "HH:MM[:SS]", with HH representing the 24-hour clock hour of the fire time.
 Date getFireTimeAfter(Date afterTime)
          Returns the first time the NthIncludedDayTrigger will fire after the specified date.
 int getIntervalType()
          Returns the interval type for the NthIncludedDayTrigger.
 int getN()
          Returns the day of the interval on which the NthIncludedDayTrigger should fire.
 int getNextFireCutoffInterval()
          Returns the nextFireCutoffInterval for the NthIncludedDayTrigger.
 Date getNextFireTime()
          Returns the next time at which the NthIncludedDayTrigger will fire.
 Date getPreviousFireTime()
          Returns the previous time at which the NthIncludedDayTrigger fired.
 Date getStartTime()
          Returns the date/time on which the trigger may begin firing.
 TimeZone getTimeZone()
          Gets the time zone in which the fireAtTime will be resolved.
 boolean mayFireAgain()
          Used by the Scheduler to determine whether or not it is possible for this Trigger to fire again.
 void setEndTime(Date endTime)
          Sets the date/time on which the trigger must stop firing.
 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.
 void setIntervalType(int intervalType)
          Sets the interval type for the NthIncludedDayTrigger.
 void setN(int n)
          Sets the day of the interval on which the NthIncludedDayTrigger should fire.
 void setNextFireCutoffInterval(int nextFireCutoffInterval)
          Sets the nextFireCutoffInterval for the NthIncludedDayTrigger.
 void setStartTime(Date startTime)
          Sets the date/time on which the trigger may begin firing.
 void setTimeZone(TimeZone timeZone)
          Sets the time zone in which the fireAtTime will be resolved.
 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).
 void updateAfterMisfire(Calendar calendar)
          Updates the NthIncludedDayTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the NthIncludedDayTrigger was created
 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.
 
Methods inherited from class org.quartz.Trigger
addTriggerListener, clearAllTriggerListeners, compareTo, equals, getCalendarName, getDescription, getFireInstanceId, getFullJobName, getFullName, getGroup, getJobDataMap, getJobGroup, getJobName, getKey, getMisfireInstruction, getName, getPriority, getTriggerListenerNames, hashCode, isVolatile, removeTriggerListener, setCalendarName, setDescription, setFireInstanceId, setGroup, setJobDataMap, setJobGroup, setJobName, setMisfireInstruction, setName, setPriority, setVolatility, toString, validate
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MISFIRE_INSTRUCTION_FIRE_ONCE_NOW

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

See Also:
Constant Field Values

MISFIRE_INSTRUCTION_DO_NOTHING

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.

See Also:
Constant Field Values

INTERVAL_TYPE_MONTHLY

public static final int INTERVAL_TYPE_MONTHLY
indicates a monthly trigger type (fires on the Nth included day of every month).

See Also:
Constant Field Values

INTERVAL_TYPE_YEARLY

public static final int INTERVAL_TYPE_YEARLY
indicates a yearly trigger type (fires on the Nth included day of every year).

See Also:
Constant Field Values

INTERVAL_TYPE_WEEKLY

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.

See Also:
Constant Field Values
Constructor Detail

NthIncludedDayTrigger

public NthIncludedDayTrigger()
Create an NthIncludedDayTrigger with no specified name, group, or 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 setName(), setGroup(), setJobName(), and setJobGroup(), must be called before the NthIncludedDayTrigger can be placed into a Scheduler.


NthIncludedDayTrigger

public NthIncludedDayTrigger(String name)
Create an NthIncludedDayTrigger with the given name and default 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

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

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 Detail

clone

public Object clone()
Overrides:
clone in class Trigger

setN

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.

Parameters:
n - the day of the interval on which the trigger should fire.
Throws:
IllegalArgumentException - the value entered for N was not valid (probably less than or equal to zero).
See Also:
getN()

getN

public int getN()
Returns the day of the interval on which the NthIncludedDayTrigger should fire.

Returns:
the value of n
See Also:
setN(int)

setIntervalType

public void setIntervalType(int intervalType)
Sets the interval type for the NthIncludedDayTrigger. If INTERVAL_TYPE_MONTHLY, the trigger will fire on the Nth included day of every month. If INTERVAL_TYPE_YEARLY, the trigger will fire on the Nth included day of every year. If INTERVAL_TYPE_WEEKLY, the trigger will fire on the Nth included day of every week.

Parameters:
intervalType - the interval type for the trigger
Throws:
IllegalArgumentException - the value of intervalType is not valid. Valid values are represented by the INTERVAL_TYPE_WEEKLY, INTERVAL_TYPE_MONTHLY and INTERVAL_TYPE_YEARLY constants.
See Also:
getIntervalType(), INTERVAL_TYPE_WEEKLY, INTERVAL_TYPE_MONTHLY, INTERVAL_TYPE_YEARLY

getIntervalType

public int getIntervalType()
Returns the interval type for the NthIncludedDayTrigger.

Returns:
the trigger's interval type
See Also:
setIntervalType(int), INTERVAL_TYPE_WEEKLY, INTERVAL_TYPE_MONTHLY, INTERVAL_TYPE_YEARLY

setFireAtTime

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.

Parameters:
fireAtTime - the time at which the trigger should fire
Throws:
IllegalArgumentException - the specified value for fireAtTime could not be successfully parsed into a valid time of day.
See Also:
getFireAtTime()

getFireAtTime

public String getFireAtTime()
Returns the fire time for the NthIncludedDayTrigger as a string with the format "HH:MM[:SS]", with HH representing the 24-hour clock hour of the fire time. Seconds are optional and their inclusion depends on whether or not they were provided to setFireAtTime(String).

Returns:
the fire time for the trigger
See Also:
setFireAtTime(String)

setNextFireCutoffInterval

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.

Parameters:
nextFireCutoffInterval - the desired cutoff interval
See Also:
getNextFireCutoffInterval(), getNextFireTime()

getNextFireCutoffInterval

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.

Returns:
the chosen cutoff interval
See Also:
setNextFireCutoffInterval(int), getNextFireTime()

setStartTime

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.

Specified by:
setStartTime in class Trigger
Parameters:
startTime - the initial boundary for trigger firings
Throws:
IllegalArgumentException - the specified start time is after the current end time or is null
See Also:
getStartTime()

getStartTime

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.

Specified by:
getStartTime in class Trigger
Returns:
the initial date/time on which the trigger may begin firing
See Also:
setStartTime(Date)

setEndTime

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.

Specified by:
setEndTime in class Trigger
Parameters:
endTime - the final boundary for trigger firings
Throws:
IllegalArgumentException - the specified end time is before the current start time
See Also:
getEndTime()

getEndTime

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.

Specified by:
getEndTime in class Trigger
Returns:
the date/time on which the trigger must stop firing
See Also:
setEndTime(Date)

setTimeZone

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.

See Also:
TimeZone.getDefault(), getTimeZone(), getFireAtTime(), setFireAtTime(String)

getTimeZone

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.

See Also:
TimeZone.getDefault(), getTimeZone(), getFireAtTime(), setFireAtTime(String)

getNextFireTime

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.

Specified by:
getNextFireTime in class Trigger
Returns:
the next fire time for the trigger
See Also:
getNextFireCutoffInterval(), setNextFireCutoffInterval(int), getFireTimeAfter(Date)

getPreviousFireTime

public Date getPreviousFireTime()
Returns the previous time at which the NthIncludedDayTrigger fired. If the trigger has not yet fired, null will be returned.

Specified by:
getPreviousFireTime in class Trigger
Returns:
the previous fire time for the trigger

getFireTimeAfter

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.

Specified by:
getFireTimeAfter in class Trigger
Parameters:
afterTime - The time after which to find the nearest fire time. This argument is treated as exclusive — that is, if afterTime is a valid fire time for the trigger, it will not be returned as the next fire time.
Returns:
the first time the trigger will fire following the specified date

getFinalFireTime

public Date getFinalFireTime()
Returns the last time the NthIncludedDayTrigger will fire. If the trigger will not fire at any point between startTime and endTime, or there is not endTime, null will be returned.

Specified by:
getFinalFireTime in class Trigger
Returns:
the last time the trigger will fire, or null if there is no last time.

triggered

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).

Specified by:
triggered in class Trigger
See Also:
Trigger.executionComplete(JobExecutionContext, JobExecutionException)

computeFirstFireTime

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.

Specified by:
computeFirstFireTime in class Trigger
Returns:
the first time at which the Trigger will be fired by the scheduler, which is also the same value getNextFireTime() will return (until after the first firing of the Trigger).

executionComplete

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.

Specified by:
executionComplete in class Trigger
Parameters:
jobCtx - the JobExecutionContext that was used by the Job's execute() method.
result - the JobExecutionException thrown by the Job, if any (may be null)
Returns:
one of the Trigger.INSTRUCTION_XXX constants.
See Also:
Trigger.INSTRUCTION_NOOP, Trigger.INSTRUCTION_RE_EXECUTE_JOB, Trigger.INSTRUCTION_DELETE_TRIGGER, Trigger.INSTRUCTION_SET_TRIGGER_COMPLETE, Trigger.triggered(Calendar)

mayFireAgain

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

Specified by:
mayFireAgain in class Trigger
Returns:
a boolean indicator of whether the trigger could potentially fire again

validateMisfireInstruction

protected boolean validateMisfireInstruction(int misfireInstruction)
Indicates whether misfireInstruction is a valid misfire instruction for this Trigger.

Specified by:
validateMisfireInstruction in class Trigger
Returns:
whether misfireInstruction is valid.

updateAfterMisfire

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.

Specified by:
updateAfterMisfire in class Trigger
Parameters:
calendar - a new or updated calendar to use for the trigger

updateWithNewCalendar

public void updateWithNewCalendar(Calendar calendar,
                                  long misfireThreshold)
Updates the NthIncludedDayTrigger's state based on the given new version of the associated Calendar.

Specified by:
updateWithNewCalendar in class Trigger
Parameters:
calendar - a new or updated calendar to use for the trigger
misfireThreshold - the amount of time (in milliseconds) that must be between "now" and the time the next firing of the trigger is supposed to occur.


Copyright 2001-2011, Terracotta, Inc.