Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.quartz
Class NthIncludedDayTrigger

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

All Implemented Interfaces:
  Cloneable, Comparable, Serializable

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 `NthIncludedDayTrigger`s 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
`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, 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
`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", 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.
`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", 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` | `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, clone, compareTo, equals, getCalendarName, getDescription, getFireInstanceId, getFullJobName, getFullName, getGroup, getJobDataMap, getJobGroup, getJobName, getMisfireInstruction, getName, getTriggerListenerNames, hashCode, isVolatile, removeTriggerListener, setCalendarName, setDescription, setFireInstanceId, setGroup, setJobDataMap, setJobGroup, setJobName, setMisfireInstruction, setName, 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,
                                 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

### 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", 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.

  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", with HH representing the 24-hour clock hour of the fire time.

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

### 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`, `null` will be returned.

  Specified by:
    `getFinalFireTime` in class `Trigger`
  Returns:
    the last time the trigger will fire.

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Quartz Enterprise Job Scheduler Project Page
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD