The Cron Expression Format

The format of the Quartz cron expression is very similar to the UNIX cron format, with a few very clear differences. One of the differences is that the Quartz format supports schedules down to the second, whereas the UNIX cron supports schedules only to the minute. Many of our firing schedules are based on second-level increments (for example, every 45 seconds), so this is a very nice difference.

With UNIX cron, the job (or command) that is to be executed is stored with the cron expression, in the sixth position. Quartz uses the cron expression to store the firing schedule. The CronTrigger, which references the cron expression, is associated with the job at schedule time.

Another difference between the UNIX cron expression format and Quartz is the number of supported fields in the expression. Where UNIX gives five (minute, hour, day, month, and dayofweek), Quartz provides seven. Table 5.1 lists the seven cron expression fields Quartz supports.

The fields are separated by a space, just as with UNIX cron. Arguably, the simplest expression we could write would look something like this:

* * * ? * *

This expression would fire the scheduled job every second, for every minute, for every hour of every day.

Understanding the Special Characters

As with UNIX cron, Quartz cron expressions support special characters that can be used to create more complicated execution schedules. However, Quartz supports many more than the standard UNIX cron expression.

The * Character

Using the asterisk (*) in a field indicates that you want to include all legal values for that field. For example, using this character in the month field means to fire the trigger for every month.

Example expression:

0 * 17 * * ?

Meaning: Fire the trigger every minute, every day starting at 5 PM until 5:59 PM. It stops at 5:59 PM because the value 17 is in the hour field, and at 6 PM, the hour becomes 18 and doesn't agree with this trigger until the next day at 5 PM.

Use the * character when you want the trigger to fire for every valid value of the field.

The ? Character

The question mark (?) character can be used only in the dayofmonth and dayofweek fields, but not at the same time. You can think of the ? character as "I don't care what value is in this field." This is different from the asterisk, which indicates every value for the field. The ? character says that no value was specified for this field.

The reasons a value can't be specified for both fields are tough to explain and even tougher to understand. Basically, if a value was specified for each, the meaning would become ambiguous: Consider if an expression had the value 11 in a field for the day of the month and a value of WED in the field for the day of the week. Should that trigger fire only on the 11th of the month if it falls on a Wednesday? Or should it fire on both the 11th and every Wednesday? The ambiguity is removed by not allowing a value in both fields at the same time.

Just remember that if you specify a value in one of the two fields, you must put a ? in the other.

Example expression:

0 10,44 14 ? 3 WED

Meaning: Fire at 2:10 PM and 2:44 PM every Wednesday in the month of March.

The , Character

The comma (,) character is used to specify a list of additional values within a given field. For example, using the value 0,15,30,45 in the second field means to fire the trigger every 15 seconds.

Example expression:

0 0,15,30,45 * * * ?

Meaning: Fire the trigger on every quarter-hour.

The / Character

The slash (/) character is used to schedule increments. We just used the comma to increment every 15 minutes, but we could have also written it like 0/15.

Example expression:

0/15 0/30 * * * ?

Meaning: Fire the trigger every 15 seconds on the hour and half-hour.

You can't increment beyond the fields range. For example, you can't specify 30/20 in the second field and expect the scheduler to fire correctly.

The Character

The hyphen (-) character is used to specify a range. For example, 3-8 in the hour field means "the hours 3, 4, 5, 6, 7, and 8." The fields will not wrap, so values such as 50-10 are not allowed.

Example expression:

0 45 3-8 ? * *

Meaning: Fire the trigger on 45 past the hours 3 AM through 8 AM.

The L Character

The L character represents the last allowed value for the field. It is supported by the dayofmonth and dayofweek fields only. When used in the dayofmonth field, it represents the last day of the month for the value specified in the month field. For example, when the month field has JAN specified, using L in the dayofmonth field would cause the trigger to fire on January 31. If SEP was specified as the month, then L would mean to fire on September 30. In order words, it means to fire the trigger on the last day of whatever month is specified.

The expression 0 0 8 L * ? means to fire the trigger at 8:00 AM the last day of every month. The * character in the month field gives us the "every month" part.

When the L character is used in the dayofweek field, it indicates the last day of the week, which is Saturday (or, numerically, 7). So if you needed to fire the trigger on the last Saturday of every month at 11:59 PM, you could use the expression 0 59 23 ? * L.

When used in the dayofweek field, you can use a numerical value in conjunction with the L character to represent the last X day of the month. For example, the expression 0 0 12 ? * 2L says to fire the trigger on the last Monday of every month.

The W Character

The W character stands for weekday (MonFri) and can be used only in the dayofmonth field. It is used to specify the weekday that is nearest to the given day. Most business processes are based on the work week, so the W character can be very important. For example, a value of 15W in the dayofmonth field means "the nearest weekday to the 15th of the month." If the 15th was on a Saturday, the trigger would fire on Friday the 14th because it's closer to the 15th than Monday, which would be the 17th in this example. The W character can be specified only when the day of the month is a single day, not a range or list of days.

The # Character

The # character can be used only in the dayofweek field. It's used to specify the nth XXX day of the month. For example, if you specified the value 6#3 in the dayofweek field, it would mean the third Friday of the month (6 = Friday and #3 means the third one in the month). Another example of 2#1 means the first Monday of the month (2 = Monday and #1 means the first one of the month). Note that if you specify #5 and there is no 5 of the given day of the week in the month, no firing will occur that month.