com.helger.quartz.impl.triggers

Class CalendarIntervalTrigger

java.lang.Object

com.helger.quartz.impl.triggers.AbstractTrigger<CalendarIntervalTrigger>

com.helger.quartz.impl.triggers.CalendarIntervalTrigger

All Implemented Interfaces:

com.helger.commons.lang.ICloneable<CalendarIntervalTrigger>, ICalendarIntervalTrigger, ITrigger, IMutableTrigger, IOperableTrigger, Comparable<ITrigger>

public class CalendarIntervalTrigger
extends AbstractTrigger<CalendarIntervalTrigger>
implements ICalendarIntervalTrigger

A concrete ITrigger that is used to fire a IJobDetail based upon repeating calendar time intervals.

The trigger will fire every N (see setRepeatInterval(int) ) units of calendar time (see setRepeatIntervalUnit(EIntervalUnit)) as specified in the trigger's definition. This trigger can achieve schedules that are not possible with ISimpleTrigger (e.g because months are not a fixed number of seconds) or ICronTrigger (e.g. because "every 5 months" is not an even divisor of 12).

If you use an interval unit of MONTH then care should be taken when setting a startTime value that is on a day near the end of the month. For example, if you choose a start time that occurs on January 31st, and have a trigger with unit MONTH and interval 1, then the next fire time will be February 28th, and the next time after that will be March 28th - and essentially each subsequent firing will occur on the 28th of the month, even if a 31st day exists. If you want a trigger that always fires on the last day of the month - regardless of the number of days in the month, you should use CronTrigger.

Since:

1.7

Author:

James House

See Also:

ITrigger, ICronTrigger, ISimpleTrigger, TriggerUtils

Nested Class Summary

Nested classes/interfaces inherited from interface com.helger.quartz.ITrigger

ITrigger.ECompletedExecutionInstruction, ITrigger.EMisfireInstruction, ITrigger.ETriggerState

Field Summary

Fields inherited from interface com.helger.quartz.ITrigger

DEFAULT_PRIORITY

Constructor Summary

Constructors

Constructor and Description
CalendarIntervalTrigger() Create a DateIntervalTrigger with no settings.
CalendarIntervalTrigger(CalendarIntervalTrigger aOther)
CalendarIntervalTrigger(String name, Date startTime, Date endTime, EIntervalUnit intervalUnit, int repeatInterval) Create a DateIntervalTrigger that will occur at the given time, and repeat at the the given interval until the given end time.
CalendarIntervalTrigger(String name, EIntervalUnit intervalUnit, int repeatInterval) Create a DateIntervalTrigger that will occur immediately, and repeat at the the given interval.
CalendarIntervalTrigger(String name, String group, Date startTime, Date endTime, EIntervalUnit intervalUnit, int repeatInterval) Create a DateIntervalTrigger that will occur at the given time, and repeat at the the given interval until the given end time.
CalendarIntervalTrigger(String name, String group, EIntervalUnit intervalUnit, int repeatInterval) Create a DateIntervalTrigger that will occur immediately, and repeat at the the given interval.
CalendarIntervalTrigger(String name, String group, String jobName, String jobGroup, Date startTime, Date endTime, EIntervalUnit intervalUnit, int repeatInterval) Create a DateIntervalTrigger that will occur at the given time, fire the identified Job and repeat at the the given interval until the given end time.

Method Summary

Modifier and Type	Method and Description
Date	computeFirstFireTime(ICalendar 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.
boolean	equals(Object o) Trigger equality is based upon the equality of the TriggerKey.
CalendarIntervalTrigger	getClone()
Date	getEndTime() Get the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).
Date	getFinalFireTime() Returns the final time at which the DateIntervalTrigger will fire, if there is no end time set, null will be returned.
Date	getFireTimeAfter(Date afterTime) Returns the next time at which the DateIntervalTrigger will fire, after the given time.
protected Date	getFireTimeAfter(Date aAfterTime, boolean ignoreEndTime)
Date	getNextFireTime() Returns the next time at which the Trigger is scheduled to fire.
Date	getPreviousFireTime() Returns the previous time at which the DateIntervalTrigger fired.
int	getRepeatInterval() Get the the time interval that will be added to the DateIntervalTrigger's fire time (in the set repeat interval unit) in order to calculate the time of the next trigger repeat.
EIntervalUnit	getRepeatIntervalUnit()
CalendarIntervalScheduleBuilder	getScheduleBuilder() Get a IScheduleBuilder that is configured to produce a schedule identical to this trigger's schedule.
Date	getStartTime() Get the time at which the Trigger should occur.
int	getTimesTriggered() Get the number of times the DateIntervalTrigger has already fired.
TimeZone	getTimeZone() Gets the time zone within which time calculations related to this trigger will be performed.
int	hashCode()
boolean	isPreserveHourOfDayAcrossDaylightSavings() If intervals are a day or greater, this property (set to true) will cause the firing of the trigger to always occur at the same time of day, (the time of day of the startTime) regardless of daylight saving time transitions.
boolean	isSkipDayIfHourDoesNotExist() If intervals are a day or greater, and preserveHourOfDayAcrossDaylightSavings property is set to true, and the hour of the day does not exist on a given day for which the trigger would fire, the day will be skipped and the trigger advanced a second interval if this property is set to true.
boolean	mayFireAgain() Determines whether or not the DateIntervalTrigger will occur again.
void	setEndTime(Date endTime) Set the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).
void	setNextFireTime(Date nextFireTime) Set the next time at which the DateIntervalTrigger should fire.
void	setPreserveHourOfDayAcrossDaylightSavings(boolean preserveHourOfDayAcrossDaylightSavings)
void	setPreviousFireTime(Date previousFireTime) Set the previous time at which the DateIntervalTrigger fired.
void	setRepeatInterval(int repeatInterval) set the the time interval that will be added to the DateIntervalTrigger's fire time (in the set repeat interval unit) in order to calculate the time of the next trigger repeat.
void	setRepeatIntervalUnit(EIntervalUnit intervalUnit) Set the interval unit - the time unit on with the interval applies.
void	setSkipDayIfHourDoesNotExist(boolean skipDayIfHourDoesNotExist)
void	setStartTime(Date startTime) The time at which the trigger's scheduling should start.
void	setTimesTriggered(int timesTriggered) Set the number of times the DateIntervalTrigger has already fired.
void	setTimeZone(TimeZone timeZone) Sets the time zone within which time calculations related to this trigger will be performed.
void	triggered(ICalendar 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(ICalendar cal) Updates the DateIntervalTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the DateIntervalTrigger was created.
void	updateWithNewCalendar(ICalendar calendar, long misfireThreshold) This method should not be used by the Quartz client.
void	validate() Validates whether the properties of the JobDetail are valid for submission into a Scheduler.
protected boolean	validateMisfireInstruction(ITrigger.EMisfireInstruction misfireInstruction)

Methods inherited from class com.helger.quartz.impl.triggers.AbstractTrigger

compareTo, executionComplete, getCalendarName, getDescription, getFireInstanceId, getFullJobName, getFullName, getGroup, getJobDataMap, getJobGroup, getJobKey, getJobName, getKey, getMisfireInstruction, getName, getPriority, getTriggerBuilder, setCalendarName, setDescription, setFireInstanceId, setGroup, setJobDataMap, setJobGroup, setJobKey, setJobName, setKey, setMisfireInstruction, setName, setPriority, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.helger.quartz.ICalendarIntervalTrigger

getTriggerBuilder

Methods inherited from interface com.helger.quartz.ITrigger

compareTo, getCalendarName, getDescription, getJobDataMap, getJobKey, getKey, getMisfireInstruction, getPriority

Constructor Detail

CalendarIntervalTrigger

public CalendarIntervalTrigger(@Nonnull
                               CalendarIntervalTrigger aOther)

CalendarIntervalTrigger

public CalendarIntervalTrigger()

Create a DateIntervalTrigger with no settings.

CalendarIntervalTrigger

public CalendarIntervalTrigger(String name,
                               EIntervalUnit intervalUnit,
                               int repeatInterval)

Create a DateIntervalTrigger that will occur immediately, and repeat at the the given interval.

CalendarIntervalTrigger

public CalendarIntervalTrigger(String name,
                               String group,
                               EIntervalUnit intervalUnit,
                               int repeatInterval)

Create a DateIntervalTrigger that will occur immediately, and repeat at the the given interval.

CalendarIntervalTrigger

public CalendarIntervalTrigger(String name,
                               Date startTime,
                               Date endTime,
                               EIntervalUnit intervalUnit,
                               int repeatInterval)

Create a DateIntervalTrigger that will occur at the given time, and repeat at the the given interval until the given end time.

Parameters:

startTime - A Date set to the time for the Trigger to fire.

endTime - A Date set to the time for the Trigger to quit repeat firing.

intervalUnit - The repeat interval unit (minutes, days, months, etc).

repeatInterval - The number of milliseconds to pause between the repeat firing.

CalendarIntervalTrigger

public CalendarIntervalTrigger(String name,
                               String group,
                               Date startTime,
                               Date endTime,
                               EIntervalUnit intervalUnit,
                               int repeatInterval)

Create a DateIntervalTrigger that will occur at the given time, and repeat at the the given interval until the given end time.

Parameters:

startTime - A Date set to the time for the Trigger to fire.

endTime - A Date set to the time for the Trigger to quit repeat firing.

intervalUnit - The repeat interval unit (minutes, days, months, etc).

repeatInterval - The number of milliseconds to pause between the repeat firing.

CalendarIntervalTrigger

public CalendarIntervalTrigger(String name,
                               String group,
                               String jobName,
                               String jobGroup,
                               Date startTime,
                               Date endTime,
                               EIntervalUnit intervalUnit,
                               int repeatInterval)

Create a DateIntervalTrigger that will occur at the given time, fire the identified Job and repeat at the the given interval until the given end time.

Parameters:

startTime - A Date set to the time for the Trigger to fire.

endTime - A Date set to the time for the Trigger to quit repeat firing.

intervalUnit - The repeat interval unit (minutes, days, months, etc).

repeatInterval - The number of milliseconds to pause between the repeat firing.

Method Detail

getStartTime

public final Date getStartTime()

Description copied from interface: ITrigger

Get the time at which the Trigger should occur.

Specified by:

getStartTime in interface ITrigger

Returns:

The start. May be null depending on the implementation

setStartTime

public final void setStartTime(Date startTime)

Description copied from interface: IMutableTrigger

The time at which the trigger's scheduling should start. May or may not be the first actual fire time of the trigger, depending upon the type of trigger and the settings of the other properties of the trigger. However the first actual first time will not be before this date.
Setting a value in the past may cause a new trigger to compute a first fire time that is in the past, which may cause an immediate misfire of the trigger.

Specified by:

setStartTime in interface IMutableTrigger

Parameters:

startTime - start time

getEndTime

@Nullable
public final Date getEndTime()

Description copied from interface: ITrigger

Get the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).

Specified by:

getEndTime in interface ITrigger

Returns:

the end time or null.

See Also:

ITrigger.getFinalFireTime()

setEndTime

public final void setEndTime(@Nullable
                             Date endTime)

Description copied from interface: IMutableTrigger

Set the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).

Specified by:

setEndTime in interface IMutableTrigger

See Also:

TriggerUtils.computeEndTimeToAllowParticularNumberOfFirings(IOperableTrigger,com.helger.quartz.ICalendar,int)

getRepeatIntervalUnit

public EIntervalUnit getRepeatIntervalUnit()

Specified by:

getRepeatIntervalUnit in interface ICalendarIntervalTrigger

Returns:

the interval unit - the time unit on with the interval applies.

setRepeatIntervalUnit

public void setRepeatIntervalUnit(EIntervalUnit intervalUnit)

Set the interval unit - the time unit on with the interval applies.

getRepeatInterval

public int getRepeatInterval()

Description copied from interface: ICalendarIntervalTrigger

Get the the time interval that will be added to the DateIntervalTrigger's fire time (in the set repeat interval unit) in order to calculate the time of the next trigger repeat.

Specified by:

getRepeatInterval in interface ICalendarIntervalTrigger

setRepeatInterval

public void setRepeatInterval(int repeatInterval)

set the the time interval that will be added to the DateIntervalTrigger's fire time (in the set repeat interval unit) in order to calculate the time of the next trigger repeat.

Throws:

IllegalArgumentException - if repeatInterval is < 0

getTimeZone

public TimeZone getTimeZone()

Description copied from interface: ICalendarIntervalTrigger

Gets the time zone within which time calculations related to this trigger will be performed.

If null, the system default TimeZone will be used.

Specified by:

getTimeZone in interface ICalendarIntervalTrigger

setTimeZone

public void setTimeZone(TimeZone timeZone)

Sets the time zone within which time calculations related to this trigger will be performed.

Parameters:

timeZone - the desired TimeZone, or null for the system default.

isPreserveHourOfDayAcrossDaylightSavings

public boolean isPreserveHourOfDayAcrossDaylightSavings()

If intervals are a day or greater, this property (set to true) will cause the firing of the trigger to always occur at the same time of day, (the time of day of the startTime) regardless of daylight saving time transitions. Default value is false.

For example, without the property set, your trigger may have a start time of 9:00 am on March 1st, and a repeat interval of 2 days. But after the daylight saving transition occurs, the trigger may start firing at 8:00 am every other day.

If however, the time of day does not exist on a given day to fire (e.g. 2:00 am in the United States on the days of daylight saving transition), the trigger will go ahead and fire one hour off on that day, and then resume the normal hour on other days. If you wish for the trigger to never fire at the "wrong" hour, then you should set the property skipDayIfHourDoesNotExist.

Specified by:

isPreserveHourOfDayAcrossDaylightSavings in interface ICalendarIntervalTrigger

See Also:

isSkipDayIfHourDoesNotExist(), getStartTime(), getTimeZone()

setPreserveHourOfDayAcrossDaylightSavings

public void setPreserveHourOfDayAcrossDaylightSavings(boolean preserveHourOfDayAcrossDaylightSavings)

isSkipDayIfHourDoesNotExist

public boolean isSkipDayIfHourDoesNotExist()

If intervals are a day or greater, and preserveHourOfDayAcrossDaylightSavings property is set to true, and the hour of the day does not exist on a given day for which the trigger would fire, the day will be skipped and the trigger advanced a second interval if this property is set to true. Defaults to false.

CAUTION! If you enable this property, and your hour of day happens to be that of daylight savings transition (e.g. 2:00 am in the United States) and the trigger's interval would have had the trigger fire on that day, then you may actually completely miss a firing on the day of transition if that hour of day does not exist on that day! In such a case the next fire time of the trigger will be computed as double (if the interval is 2 days, then a span of 4 days between firings will occur).

Specified by:

isSkipDayIfHourDoesNotExist in interface ICalendarIntervalTrigger

See Also:

isPreserveHourOfDayAcrossDaylightSavings()

setSkipDayIfHourDoesNotExist

public void setSkipDayIfHourDoesNotExist(boolean skipDayIfHourDoesNotExist)

getTimesTriggered

public int getTimesTriggered()

Description copied from interface: ICalendarIntervalTrigger

Get the number of times the DateIntervalTrigger has already fired.

Specified by:

getTimesTriggered in interface ICalendarIntervalTrigger

setTimesTriggered

public void setTimesTriggered(int timesTriggered)

Set the number of times the DateIntervalTrigger has already fired.

validateMisfireInstruction

protected boolean validateMisfireInstruction(ITrigger.EMisfireInstruction misfireInstruction)

Specified by:

validateMisfireInstruction in class AbstractTrigger<CalendarIntervalTrigger>

updateAfterMisfire

public void updateAfterMisfire(ICalendar cal)

Updates the DateIntervalTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the DateIntervalTrigger was created.

If the misfire instruction is set to MISFIRE_INSTRUCTION_SMART_POLICY, then the following scheme will be used:

• The instruction will be interpreted as MISFIRE_INSTRUCTION_FIRE_ONCE_NOW

Specified by:

updateAfterMisfire in interface IOperableTrigger

triggered

public void triggered(ICalendar 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 interface IOperableTrigger

See Also:

AbstractTrigger.executionComplete(IJobExecutionContext, JobExecutionException)

updateWithNewCalendar

public void updateWithNewCalendar(ICalendar calendar,
                                  long misfireThreshold)

Description copied from interface: IOperableTrigger

This method should not be used by the Quartz client.
To be implemented by the concrete class.
The implementation should update the Trigger's state based on the given new version of the associated Calendar (the state should be updated so that it's next fire time is appropriate given the Calendar's new settings).

Specified by:

updateWithNewCalendar in interface IOperableTrigger

See Also:

IOperableTrigger.updateWithNewCalendar(com.helger.quartz.ICalendar, long)

computeFirstFireTime

public Date computeFirstFireTime(ICalendar 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 interface IOperableTrigger

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

getNextFireTime

public Date getNextFireTime()

Returns the next time at which the Trigger is scheduled to fire. If the trigger will not fire again, null will be returned. Note that the time returned can possibly be in the past, if the time that was computed for the trigger to next fire has already arrived, but the scheduler has not yet been able to fire the trigger (which would likely be due to lack of resources e.g. threads).

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

Specified by:

getNextFireTime in interface ITrigger

See Also:

TriggerUtils.computeFireTimesBetween(com.helger.quartz.spi.IOperableTrigger, ICalendar, Date, Date)

getPreviousFireTime

public Date getPreviousFireTime()

Returns the previous time at which the DateIntervalTrigger fired. If the trigger has not yet fired, null will be returned.

Specified by:

getPreviousFireTime in interface ITrigger

setNextFireTime

public void setNextFireTime(Date nextFireTime)

Set the next time at which the DateIntervalTrigger should fire.

This method should not be invoked by client code.

Specified by:

setNextFireTime in interface IOperableTrigger

setPreviousFireTime

public void setPreviousFireTime(Date previousFireTime)

Set the previous time at which the DateIntervalTrigger fired.

This method should not be invoked by client code.

Specified by:

setPreviousFireTime in interface IOperableTrigger

getFireTimeAfter

public Date getFireTimeAfter(Date afterTime)

Returns the next time at which the DateIntervalTrigger will fire, after the given time. If the trigger will not fire after the given time, null will be returned.

Specified by:

getFireTimeAfter in interface ITrigger

getFireTimeAfter

protected Date getFireTimeAfter(Date aAfterTime,
                                boolean ignoreEndTime)

getFinalFireTime

public Date getFinalFireTime()

Returns the final time at which the DateIntervalTrigger will fire, if there is no end time set, null will be returned.

Note that the return time may be in the past.

Specified by:

getFinalFireTime in interface ITrigger

mayFireAgain

public boolean mayFireAgain()

Determines whether or not the DateIntervalTrigger will occur again.

Specified by:

mayFireAgain in interface ITrigger

validate

public void validate()
              throws SchedulerException

Validates whether the properties of the JobDetail are valid for submission into a Scheduler.

Specified by:

validate in interface IOperableTrigger

Overrides:

validate in class AbstractTrigger<CalendarIntervalTrigger>

Throws:

IllegalStateException - if a required property (such as Name, Group, Class) is not set.

SchedulerException

getScheduleBuilder

public CalendarIntervalScheduleBuilder getScheduleBuilder()

Get a IScheduleBuilder that is configured to produce a schedule identical to this trigger's schedule.

Specified by:

getScheduleBuilder in interface ITrigger

Specified by:

getScheduleBuilder in class AbstractTrigger<CalendarIntervalTrigger>

See Also:

AbstractTrigger.getTriggerBuilder()

getClone

@Nonnull
 @ReturnsMutableCopy
public CalendarIntervalTrigger getClone()

Specified by:

getClone in interface com.helger.commons.lang.ICloneable<CalendarIntervalTrigger>

Specified by:

getClone in interface ITrigger

Specified by:

getClone in interface IMutableTrigger

Specified by:

getClone in interface IOperableTrigger

equals

public boolean equals(Object o)

Description copied from class: AbstractTrigger

Trigger equality is based upon the equality of the TriggerKey.

Specified by:

equals in interface ITrigger

Overrides:

equals in class AbstractTrigger<CalendarIntervalTrigger>

Returns:

true if the key of this Trigger equals that of the given Trigger.

hashCode

public int hashCode()

Overrides:

hashCode in class AbstractTrigger<CalendarIntervalTrigger>