Quartz Scheduler(2.2.1) - Usage of CronTriggers

Cron is a UNIX tool that has been around for a long time, so its scheduling capabilities are powerful and proven. The CronTrigger class is based on the scheduling capabilities of cron.

CronTrigger uses “cron expressions”, which are able to create firing schedules such as: “At 8:00am every Monday through Friday” or “At 1:30am every last Friday of the month.”

CronTrigger is often more useful than SimpleTrigger, if you need a job-firing schedule that recurs based on calendar-like notions, rather than on the exactly specified intervals of SimpleTrigger.

With CronTrigger, you can specify firing-schedules such as “every Friday at noon”, or “every weekday and 9:30 am”, or even “every 5 minutes between 9:00 am and 10:00 am on every Monday, Wednesday and Friday during January”.

Even so, like SimpleTrigger, CronTrigger has a startTime which specifies when the schedule is in force, and an (optional) endTime that specifies when the schedule should be discontinued.

Cron Expressions

Cron-Expressions are used to configure instances of CronTrigger. Cron-Expressions are strings that are actually made up of seven sub-expressions, that describe individual details of the schedule. These sub-expression are separated with white-space, and represent:

Seconds

Minutes

Hours

Day-of-Month

Month

Day-of-Week

Year (optional field)

An example of a complete cron-expression is the string “0 0 12 ? WED”* - which means “every Wednesday at 12:00:00 pm”.

Individual sub-expressions can contain ranges and/or lists. For example, the day of week field in the previous (which reads “WED”) example could be replaced with “MON-FRI”, “MON,WED,FRI”, or even “MON-WED,SAT”.

Wild-cards (the '' character) can be used to say “every” possible value of this field. Therefore the '' character in the “Month” field of the previous example simply means “every month”. A '*' in the Day-Of-Week field would therefore obviously mean “every day of the week”.

All of the fields have a set of valid values that can be specified. These values should be fairly obvious - such as the numbers 0 to 59 for seconds and minutes, and the values 0 to 23 for hours. Day-of-Month can be any value 1-31, but you need to be careful about how many days are in a given month! Months can be specified as values between 0 and 11, or by using the strings JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV and DEC. Days-of-Week can be specified as values between 1 and 7 (1 = Sunday) or by using the strings SUN, MON, TUE, WED, THU, FRI and SAT.

The '/' character can be used to specify increments to values. For example, if you put '0/15' in the Minutes field, it means 'every 15th minute of the hour, starting at minute zero'. If you used '3/20' in the Minutes field, it would mean 'every 20th minute of the hour, starting at minute three' - or in other words it is the same as specifying '3,23,43' in the Minutes field. Note the subtlety that “/35” does not* mean “every 35 minutes” - it means “every 35th minute of the hour, starting at minute zero” - or in other words the same as specifying '0,35'.

The '?' character is allowed for the day-of-month and day-of-week fields. It is used to specify “no specific value”. This is useful when you need to specify something in one of the two fields, but not the other. See the examples below (and CronTrigger Javadoc) for clarification.

The 'L' character is allowed for the day-of-month and day-of-week fields. This character is short-hand for “last”, but it has different meaning in each of the two fields. For example, the value “L” in the day-of-month field means “the last day of the month” - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means “7” or “SAT”. But if used in the day-of-week field after another value, it means “the last xxx day of the month” - for example “6L” or “FRIL” both mean “the last Friday of the month”. You can also specify an offset from the last day of the month, such as “L-3” which would mean the third-to-last day of the calendar month. When using the 'L' option, it is important not to specify lists, or ranges of values, as you'll get confusing/unexpected results.

The 'W' is used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify “15W” as the value for the day-of-month field, the meaning is: “the nearest weekday to the 15th of the month”.

The '#' is used to specify “the nth” XXX weekday of the month. For example, the value of “6#3” or “FRI#3” in the day-of-week field means “the third Friday of the month”.

Format

The fields are as follows:

Field Name	Mandatory	Allowed Values	Allowed Special Characters
Seconds	YES	0-59	, - *
Minutes	YES	0-59	, - *
Hours	YES	0-23	, - *
Day of month	YES	1-31	, - * ? / L W
Month	YES	1-12 or JAN-DEC	, - *
Day of week	YES	1-7 or SUN-SAT	, - * ? / L #
Year	NO	empty, 1970-2099	, - *

So cron expressions can be as simple as this: * * * * ? *, or more complex, like this: 0/5 14,18,3-39,52 * ? JAN,MAR,SEP MON-FRI 2002-2010

Special characters

1. * (all values) - used to select all values within a field. For example, “*” in the minute field means “ every minute”.

2. ? (“no specific value”) - useful when you need to specify something in one of the two fields in which the character is allowed, but not the other. For example, if you want your trigger to fire on a particular day of the month (say, the 10th), but don't care what day of the week that happens to be, you would put “10” in the day-of-month field, and “?” in the day-of-week field. See the examples below for clarification.

3. - - used to specify ranges. For example, “10-12” in the hour field means “the hours 10, 11 and 12.”

4. , - used to specify additional values. For example, “MON,WED,FRI” in the day-of-week field means “the days Monday, Wednesday, and Friday”.

5. / - used to specify increments. For example, “0/15” in the seconds field means “the seconds 0, 15, 30, and 45". And “5/15” in the seconds field means “the seconds 5, 20, 35, and 50,” You can also specify '/' after the '' character - in this case '' is equivalent to having '0' before the '/'. '1/3' in the day-of-month field means “fire every 3 days starting on the first day of the month”.

6. L (“last”) - has different meaning in each of the two fields in which it is allowed. For example, the value “L” in the day-of-month field means “the last day of the month” - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means “7” or “SAT”. But if used in the day-of-week field after another value, it means “the last xxx day of the month” - for example “6L” means “the last Friday of the month”. You can also specify an offset from the last day of the month, such as “L-3” which would mean the third-to-last day of the calendar month. When using the 'L' option, it is important not to specify lists, or ranges of values, as you'll get confusing/unexpected results.

7. >W (“weekday”) - used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify “15W” as the value for the day-of-month field, the meaning is: “the nearest weekday to the 15th of the month”. So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify “1W” as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days. The 'W' character can only be specified when the day-of-month is a single day, not a range or list of days.

8. # - used to specify “the nth” XXX day of the month. For example, the value of “6#3” in the day-of-week field means “the third Friday of the month” (day 6 = Friday and “#3” = the 3rd one in the month). Other examples: “2#1” = the first Monday of the month and “4#5” = the fifth Wednesday of the month. Note that if you specify “#5” and there is not 5 of the given day-of-week in the month, then no firing will occur that month.

Examples

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 L-2 * ?	>Fire at 10:15am on the 2nd-to-last day 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
0 0 12 1/5 * ?	>Fire at 12pm (noon) every 5 days every month, starting on the first day of the month.
0 11 11 11 11 ?	Fire every November 11th at 11:11am.

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

Notes

1. Support for specifying both a day-of-week and a day-of-month value is not complete (you must currently use the '?' character in one of these fields).

2. Be careful when setting fire times between the hours of the morning when “daylight savings” changes occur in your locale (for US locales, this would typically be the hour before and after 2:00 AM - because the time shift can cause a skip or a repeat depending on whether the time moves back or jumps forward. You may find this Wikipedia entry helpful in determining the specifics to your locale: https://secure.wikimedia.org/wikipedia/en/wiki/Daylight_saving_time_around_the_world

Building CronTriggers

CronTrigger instances are built using TriggerBuilder (for the trigger's main properties) and CronScheduleBuilder (for the CronTrigger-specific properties).

Build a trigger that will fire every other minute, between 8am and 5pm, every day

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(CronScheduleBuilder.cronSchedule("0 0/2 8-17 * * ?"))

    .forJob("myJob", "group1")

    .build();

Build a trigger that will fire daily at 10:42 am

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(DateBuilder.dailyAtHourAndMinute(10, 42))

    .forJob(myJobKey)

    .build();

or -

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(CronScheduleBuilder.cronSchedule("0 42 10 * * ?"))

    .forJob(myJobKey)

    .build();

Build a trigger that will fire on Wednesdays at 10:42 am, in a Timezone other than the system's default

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(DateBuilder.weeklyOnDayAndHourAndMinute(DateBuilder.WEDNESDAY, 10, 42))

    .forJob(myJobKey)

    .inTimeZone(TimeZone.getTimeZone("America/Los_Angeles"))

    .build();

or -

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(CronScheduleBuilder.cronSchedule("0 42 10 ? * WED"))

    .inTimeZone(TimeZone.getTimeZone("America/Los_Angeles"))

    .forJob(myJobKey)

    .build();

CronTrigger Misfire Instructions

The following instructions can be used to inform Quartz what it should do when a misfire occurs for CronTrigger. (Misfire situations were introduced in the More About Triggers section of this tutorial). These instructions are defined as constants on CronTrigger itself (including Javadoc describing their behavior). The instructions include:

MISFIRE_INSTRUCTION_IGNORE_MISFIRE_POLICY

MISFIRE_INSTRUCTION_DO_NOTHING

MISFIRE_INSTRUCTION_FIRE_NOW

All triggers also have the MISFIRE_INSTRUCTION_SMART_POLICY instruction available for use, and this instruction is also the default for all trigger types. The 'smart policy' instruction is interpreted by CronTrigger as MISFIRE_INSTRUCTION_FIRE_NOW. The Javadoc for the CronTrigger.updateAfterMisfire() method explains the exact details of this behavior.

When building CronTriggers, you specify the misfire instruction as part of the simple schedule (via CronSchedulerBuilder):

trigger = TriggerBuilder.newTrigger()

    .withIdentity("trigger3", "group1")

    .withSchedule(CronScheduleBuilder.cronSchedule("0 0/2 8-17 * * ?")

        .withMisfireHandlingInstructionFireAndProceed())

    .forJob("myJob", "group1")

    .build();