org.quartz
Class CronTrigger

java.lang.Object
  org.quartz.Trigger
      org.quartz.CronTrigger

All Implemented Interfaces:

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

public class CronTrigger
extends Trigger

A concrete Trigger that is used to fire a JobDetail at given moments in time, defined with Unix 'cron-like' definitions.

For those unfamiliar with "cron", this means being able to create a firing schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am every last Friday of the month".

The format of a "Cron-Expression" string is documented on the CronExpression class.

Here are some full examples:

Expression		Meaning
"0 0 12 * * ?"		Fire at 12pm (noon) every day
"0 15 10 ? * *"		Fire at 10:15am every day
"0 15 10 * * ?"		Fire at 10:15am every day
"0 15 10 * * ? *"		Fire at 10:15am every day
"0 15 10 * * ? 2005"		Fire at 10:15am every day during the year 2005
"0 * 14 * * ?"		Fire every minute starting at 2pm and ending at 2:59pm, every day
"0 0/5 14 * * ?"		Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
"0 0/5 14,18 * * ?"		Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
"0 0-5 14 * * ?"		Fire every minute starting at 2pm and ending at 2:05pm, every day
"0 10,44 14 ? 3 WED"		Fire at 2:10pm and at 2:44pm every Wednesday in the month of March.
"0 15 10 ? * MON-FRI"		Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
"0 15 10 15 * ?"		Fire at 10:15am on the 15th day of every month
"0 15 10 L * ?"		Fire at 10:15am on the last day of every month
"0 15 10 ? * 6L"		Fire at 10:15am on the last Friday of every month
"0 15 10 ? * 6L"		Fire at 10:15am on the last Friday of every month
"0 15 10 ? * 6L 2002-2005"		Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005
"0 15 10 ? * 6#3"		Fire at 10:15am on the third Friday of every month

Pay attention to the effects of '?' and '*' in the day-of-week and day-of-month fields!

NOTES:

• Support for specifying both a day-of-week and a day-of-month value is not complete (you'll need to use the '?' character in on of these fields).
• Be careful when setting fire times between mid-night and 1:00 AM - "daylight savings" can cause a skip or a repeat depending on whether the time moves back or jumps forward.

Author:

Sharada Jambula, James House, Contributions from Mads Henderson

See Also:

Trigger, SimpleTrigger, TriggerUtils, Serialized Form

Field Summary

static int	MISFIRE_INSTRUCTION_DO_NOTHING Instructs the Scheduler that upon a mis-fire situation, the CronTrigger wants to have it's next-fire-time updated to the next time in the schedule after the current time (taking into account any associated Calendar, 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 CronTrigger wants to be fired now by Scheduler.
protected static int	YEAR_TO_GIVEUP_SCHEDULING_AT

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

CronTrigger()
Create a CronTrigger with no settings.

CronTrigger(java.lang.String name)
Create a CronTrigger with the given name and default group.

CronTrigger(java.lang.String name, java.lang.String group)
Create a CronTrigger with the given name and group.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String cronExpression)
Create a CronTrigger with the given name, group and expression.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup)
Create a CronTrigger with the given name and group, and associated with the identified JobDetail.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup, java.util.Date startTime, java.util.Date endTime, java.lang.String cronExpression)
Create a CronTrigger that will occur at the given time, until the given end time.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup, java.util.Date startTime, java.util.Date endTime, java.lang.String cronExpression, java.util.TimeZone timeZone)
Create a CronTrigger with fire time dictated by the cronExpression resolved with respect to the specified timeZone occurring from the startTime until the given endTime.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup, java.lang.String cronExpression)
Create a CronTrigger with the given name and group, associated with the identified JobDetail, and with the given "cron" expression.

CronTrigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup, java.lang.String cronExpression, java.util.TimeZone timeZone)
Create a CronTrigger with the given name and group, associated with the identified JobDetail, and with the given "cron" expression resolved with respect to the TimeZone.

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 context, 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.lang.String	getCronExpression()
java.util.Date	getEndTime() Get the time at which the CronTrigger should quit repeating - even if repeastCount isn't yet satisfied.
java.lang.String	getExpressionSummary()
java.util.Date	getFinalFireTime() NOT YET IMPLEMENTED: Returns the final time at which the CronTrigger will fire.
java.util.Date	getFireTimeAfter(java.util.Date afterTime) Returns the next time at which the CronTrigger will fire, after the given time.
java.util.Date	getNextFireTime() Returns the next time at which the Trigger is scheduled to fire.
java.util.Date	getPreviousFireTime() Returns the previous time at which the CronTrigger fired.
java.util.Date	getStartTime() Get the time at which the CronTrigger should occur.
protected java.util.Date	getTimeAfter(java.util.Date afterTime)
protected java.util.Date	getTimeBefore(java.util.Date endTime) NOT YET IMPLEMENTED: Returns the time before the given time that this CronTrigger will fire.
java.util.TimeZone	getTimeZone() Returns the time zone for which the cronExpression of this CronTrigger will be resolved.
boolean	hasAdditionalProperties() Used by extensions of CronTrigger to imply that there are additional properties, specifically so that extensions can choose whether to be stored as a serialized blob, or as a flattened CronTrigger table.
boolean	mayFireAgain() Determines whether or not the CronTrigger will occur again.
void	setCronExpression(CronExpression cronExpression) Set the CronExpression to the given one.
void	setCronExpression(java.lang.String cronExpression)
void	setEndTime(java.util.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(java.util.Date nextFireTime) Sets the next time at which the CronTrigger will fire.
void	setPreviousFireTime(java.util.Date previousFireTime) Set the previous time at which the CronTrigger fired.
void	setStartTime(java.util.Date startTime) The time at which the trigger's scheduling should start.
void	setTimeZone(java.util.TimeZone timeZone) Sets the time zone for which the cronExpression of this CronTrigger 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 cal) Updates the CronTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the CronTrigger was created.
void	updateWithNewCalendar(Calendar calendar, long misfireThreshold) This method should not be used by the Quartz client.
protected boolean	validateMisfireInstruction(int misfireInstruction)
boolean	willFireOn(java.util.Calendar test) Determines whether the date and (optionally) time of the given Calendar instance falls on a scheduled fire-time of this trigger.
boolean	willFireOn(java.util.Calendar test, boolean dayOnly) Determines whether the date and (optionally) time of the given Calendar instance falls on a scheduled fire-time of 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 CronTrigger wants to be fired now by 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 CronTrigger wants to have it's next-fire-time updated to the next time in the schedule after the current time (taking into account any associated Calendar, but it does not want to be fired now.

See Also:

Constant Field Values

YEAR_TO_GIVEUP_SCHEDULING_AT

protected static final int YEAR_TO_GIVEUP_SCHEDULING_AT

See Also:

Constant Field Values

Constructor Detail

CronTrigger

public CronTrigger()

Create a CronTrigger with no settings.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

CronTrigger

public CronTrigger(java.lang.String name)

Create a CronTrigger with the given name and default group.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group)

Create a CronTrigger with the given name and group.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String cronExpression)
            throws java.text.ParseException

Create a CronTrigger with the given name, group and expression.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

Throws:

java.text.ParseException

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String jobName,
                   java.lang.String jobGroup)

Create a CronTrigger with the given name and group, and associated with the identified JobDetail.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String jobName,
                   java.lang.String jobGroup,
                   java.lang.String cronExpression)
            throws java.text.ParseException

Create a CronTrigger with the given name and group, associated with the identified JobDetail, and with the given "cron" expression.

The start-time will also be set to the current time, and the time zone will be set the the system's default time zone.

Throws:

java.text.ParseException

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String jobName,
                   java.lang.String jobGroup,
                   java.lang.String cronExpression,
                   java.util.TimeZone timeZone)
            throws java.text.ParseException

Create a CronTrigger with the given name and group, associated with the identified JobDetail, and with the given "cron" expression resolved with respect to the TimeZone.

Throws:

java.text.ParseException

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String jobName,
                   java.lang.String jobGroup,
                   java.util.Date startTime,
                   java.util.Date endTime,
                   java.lang.String cronExpression)
            throws java.text.ParseException

Create a CronTrigger that will occur at the given time, until the given end time.

If null, the start-time will also be set to the current time, the time zone will be set the the system's default.

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.

Throws:

java.text.ParseException

CronTrigger

public CronTrigger(java.lang.String name,
                   java.lang.String group,
                   java.lang.String jobName,
                   java.lang.String jobGroup,
                   java.util.Date startTime,
                   java.util.Date endTime,
                   java.lang.String cronExpression,
                   java.util.TimeZone timeZone)
            throws java.text.ParseException

Create a CronTrigger with fire time dictated by the cronExpression resolved with respect to the specified timeZone occurring from the startTime until the given endTime.

If null, the start-time will also be set to the current time. If null, the time zone will be set to the system's default.

Parameters:

name - of the Trigger

group - of the Trigger

jobName - name of the JobDetail executed on firetime

jobGroup - group of the JobDetail executed on firetime

startTime - A Date set to the earliest time for the Trigger to start firing.

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

cronExpression - A cron expression dictating the firing sequence of the Trigger

timeZone - Specifies for which time zone the cronExpression should be interpreted, i.e. the expression 0 0 10 * * ?, is resolved to 10:00 am in this time zone.

Throws:

java.text.ParseException - if the cronExpression is invalid.

Method Detail

clone

public java.lang.Object clone()

Overrides:

clone in class Trigger

setCronExpression

public void setCronExpression(java.lang.String cronExpression)
                       throws java.text.ParseException

Throws:

java.text.ParseException

getCronExpression

public java.lang.String getCronExpression()

setCronExpression

public void setCronExpression(CronExpression cronExpression)

Set the CronExpression to the given one. The TimeZone on the passed-in CronExpression over-rides any that was already set on the Trigger.

Parameters:

cronExpression -

getStartTime

public java.util.Date getStartTime()

Get the time at which the CronTrigger should occur.

Specified by:

getStartTime in class Trigger

setStartTime

public void setStartTime(java.util.Date startTime)

Description copied from class: Trigger

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 class Trigger

getEndTime

public java.util.Date getEndTime()

Get the time at which the CronTrigger should quit repeating - even if repeastCount isn't yet satisfied.

Specified by:

getEndTime in class Trigger

See Also:

getFinalFireTime()

setEndTime

public void setEndTime(java.util.Date endTime)

Description copied from class: Trigger

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 class Trigger

See Also:

TriggerUtils.computeEndTimeToAllowParticularNumberOfFirings(Trigger, Calendar, int)

getNextFireTime

public java.util.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 class Trigger

See Also:

TriggerUtils.computeFireTimesBetween(Trigger, org.quartz.Calendar , Date, Date)

getPreviousFireTime

public java.util.Date getPreviousFireTime()

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

Specified by:

getPreviousFireTime in class Trigger

setNextFireTime

public void setNextFireTime(java.util.Date nextFireTime)

Sets the next time at which the CronTrigger will fire. This method should not be invoked by client code.

setPreviousFireTime

public void setPreviousFireTime(java.util.Date previousFireTime)

Set the previous time at which the CronTrigger fired.

This method should not be invoked by client code.

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone for which the cronExpression of this CronTrigger will be resolved.

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)

Sets the time zone for which the cronExpression of this CronTrigger will be resolved.

If setCronExpression(CronExpression) is called after this method, the TimeZon setting on the CronExpression will "win". However if setCronExpression(String) is called after this method, the time zone applied by this method will remain in effect, since the String cron expression does not carry a time zone!

getFireTimeAfter

public java.util.Date getFireTimeAfter(java.util.Date afterTime)

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

Note that the date returned is NOT validated against the related org.quartz.Calendar (if any)

Specified by:

getFireTimeAfter in class Trigger

getFinalFireTime

public java.util.Date getFinalFireTime()

NOT YET IMPLEMENTED: Returns the final time at which the CronTrigger will fire.

Note that the return time *may* be in the past. and the date returned is not validated against org.quartz.calendar

Specified by:

getFinalFireTime in class Trigger

mayFireAgain

public boolean mayFireAgain()

Determines whether or not the CronTrigger will occur again.

Specified by:

mayFireAgain in class Trigger

validateMisfireInstruction

protected boolean validateMisfireInstruction(int misfireInstruction)

Specified by:

validateMisfireInstruction in class Trigger

updateAfterMisfire

public void updateAfterMisfire(Calendar cal)

Updates the CronTrigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the CronTrigger 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 class Trigger

willFireOn

public boolean willFireOn(java.util.Calendar test)

Determines whether the date and (optionally) time of the given Calendar instance falls on a scheduled fire-time of this trigger.

Equivalent to calling willFireOn(cal, false).

Parameters:

test - the date to compare

See Also:

willFireOn(Calendar, boolean)

willFireOn

public boolean willFireOn(java.util.Calendar test,
                          boolean dayOnly)

Determines whether the date and (optionally) time of the given Calendar instance falls on a scheduled fire-time of this trigger.

Note that the value returned is NOT validated against the related org.quartz.Calendar (if any)

Parameters:

test - the date to compare

dayOnly - if set to true, the method will only determine if the trigger will fire during the day represented by the given Calendar (hours, minutes and seconds will be ignored).

See Also:

willFireOn(Calendar)

executionComplete

public int executionComplete(JobExecutionContext context,
                             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:

context - is the JobExecutionContext that was used by the Job'sexecute(xx) method.

result - is 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, triggered(Calendar)

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:

executionComplete(JobExecutionContext, JobExecutionException)

updateWithNewCalendar

public void updateWithNewCalendar(Calendar calendar,
                                  long misfireThreshold)

Description copied from class: Trigger

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 class Trigger

See Also:

Trigger.updateWithNewCalendar(org.quartz.Calendar, long)

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

getExpressionSummary

public java.lang.String getExpressionSummary()

hasAdditionalProperties

public boolean hasAdditionalProperties()

Used by extensions of CronTrigger to imply that there are additional properties, specifically so that extensions can choose whether to be stored as a serialized blob, or as a flattened CronTrigger table.

getTimeAfter

protected java.util.Date getTimeAfter(java.util.Date afterTime)

getTimeBefore

protected java.util.Date getTimeBefore(java.util.Date endTime)

NOT YET IMPLEMENTED: Returns the time before the given time that this CronTrigger will fire.