org.quartz
Class NthIncludedDayTrigger

java.lang.Object
  org.quartz.Trigger
      org.quartz.NthIncludedDayTrigger

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public class NthIncludedDayTrigger
extends Trigger

A trigger which fires on the N^th 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 N^th day of the month or year is, NthIncludedDayTrigger will skip excluded days on the associated calendar. This would commonly be used in an N^th business day situation, in which the user wishes to fire a particular job on the N^th business day (i.e. the 5^th 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 N^th 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 8^th of July (because of the July 4 holiday), the 5^th of August, and the 8^th 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(java.lang.String name)
Create an NthIncludedDayTrigger with the given name and default group but no specified JobDetail.

NthIncludedDayTrigger(java.lang.String name, java.lang.String group)
Create an NthIncludedDayTrigger with the given name and group but no specified JobDetail.

NthIncludedDayTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup)
Create an NthIncludedDayTrigger with the given name and group and the specified JobDetail.

Method Summary

java.lang.Object	clone()
java.util.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.
java.util.Date	getEndTime() Returns the date/time on which the trigger must stop firing.
java.util.Date	getFinalFireTime() Returns the last time the NthIncludedDayTrigger will fire.
java.lang.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.
java.util.Date	getFireTimeAfter(java.util.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.
java.util.Date	getNextFireTime() Returns the next time at which the NthIncludedDayTrigger will fire.
java.util.Date	getPreviousFireTime() Returns the previous time at which the NthIncludedDayTrigger fired.
java.util.Date	getStartTime() Returns the date/time on which the trigger may begin firing.
java.util.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(java.util.Date endTime) Sets the date/time on which the trigger must stop firing.
void	setFireAtTime(java.lang.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(java.util.Date startTime) Sets the date/time on which the trigger may begin firing.
void	setTimeZone(java.util.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 N^th 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 N^th 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 N^th 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 3^rd included day of the week, which would be 4^th 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(java.lang.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(java.lang.String name,
                             java.lang.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(java.lang.String name,
                             java.lang.String group,
                             java.lang.String jobName,
                             java.lang.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 java.lang.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 N^th day of the interval does not exist (i.e. the 32^nd 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:

java.lang.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 N^th included day of every month. If INTERVAL_TYPE_YEARLY, the trigger will fire on the N^th included day of every year. If INTERVAL_TYPE_WEEKLY, the trigger will fire on the N^th included day of every week.

Parameters:

intervalType - the interval type for the trigger

Throws:

java.lang.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(java.lang.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:

java.lang.IllegalArgumentException - the specified value for fireAtTime could not be successfully parsed into a valid time of day.

See Also:

getFireAtTime()

getFireAtTime

public java.lang.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(java.util.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:

java.lang.IllegalArgumentException - the specified start time is after the current end time or is null

See Also:

getStartTime()

getStartTime

public java.util.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(java.util.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:

java.lang.IllegalArgumentException - the specified end time is before the current start time

See Also:

getEndTime()

getEndTime

public java.util.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(java.util.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 java.util.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 java.util.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 java.util.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 java.util.Date getFireTimeAfter(java.util.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 java.util.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 java.util.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.