diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 7b1a54a5f9..1115328d8e 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -4948,8 +4948,9 @@ default). The following listing shows the available methods for `Trigger` implem ==== `Trigger` Implementations Spring provides two implementations of the `Trigger` interface. The most interesting one -is the `CronTrigger`. It enables the scheduling of tasks based on cron expressions. For -example, the following task is scheduled to run 15 minutes past each hour but only +is the `CronTrigger`. It enables the scheduling of tasks based on +<>. +For example, the following task is scheduled to run 15 minutes past each hour but only during the 9-to-5 "`business hours`" on weekdays: [source,java,indent=0] @@ -5087,7 +5088,8 @@ number of milliseconds to wait before the first execution of the method, as the } ---- -If simple periodic scheduling is not expressive enough, you can provide a cron expression. +If simple periodic scheduling is not expressive enough, you can provide a +<>. The following example runs only on weekdays: [source,java,indent=0] @@ -5413,7 +5415,8 @@ milliseconds to wait after each task execution has completed. Another option is `fixed-rate`, indicating how often the method should be run regardless of how long any previous execution takes. Additionally, for both `fixed-delay` and `fixed-rate` tasks, you can specify an 'initial-delay' parameter, indicating the number of milliseconds to wait -before the first execution of the method. For more control, you can instead provide a `cron` attribute. +before the first execution of the method. For more control, you can instead provide a `cron` attribute +to provide a <>. The following example shows these other options: [source,xml,indent=0] @@ -5430,6 +5433,93 @@ The following example shows these other options: +[[scheduling-cron-expression]] +=== Cron Expressions + +All Spring cron expressions have to conform to the same format, whether you are using them in +<>, +<>, +or someplace else. +A well-formed cron expression, such as `* * * * * *`, consists of six space-separated time and date +fields, each with its own range of valid values: + + +.... + ┌───────────── second (0-59) + │ ┌───────────── minute (0 - 59) + │ │ ┌───────────── hour (0 - 23) + │ │ │ ┌───────────── day of the month (1 - 31) + │ │ │ │ ┌───────────── month (1 - 12) (or JAN-DEC) + │ │ │ │ │ ┌───────────── day of the week (0 - 7) + │ │ │ │ │ │ (0 or 7 is Sunday, or MON-SUN) + │ │ │ │ │ │ + * * * * * * +.... + +There are some rules that apply: + +* A field may be an asterisk (`*`), which always stands for "`first-last`". +For the day-of-the-month or day-of-the-week fields, a question mark (`?`) may be used instead of an +asterisk. +* Commas (`,`) are used to separate items of a list. +* Two numbers separated with a hyphen (`-`) express a range of numbers. +The specified range is inclusive. +* Following a range (or `*`) with `/` specifies the interval of the number's value through the range. +* English names can also be used for the day-of-month and day-of-week fields. +Use the first three letters of the particular day or month (case does not matter). +* The day-of-month and day-of-week fields can contain a `L` character, which has a different meaning +** In the day-of-month field, `L` stands for _the last day of the month_. +If followed by a negative offset (that is, `L-n`), it means _``n``th-to-last day of the month_. +** In the day-of-week field, `L` stands for _the last day of the week_. +If prefixed by a number or three-letter name (`dL` or `DDDL`), it means _the last day of week (`d` +or `DDD`) in the month_. +* The day-of-month field can be `nW`, which stands for _the nearest weekday to day of the month ``n``_. +If `n` falls on Saturday, this yields the Friday before it. +If `n` falls on Sunday, this yields the Monday after, which also happens if `n` is `1` and falls on +a Saturday (that is: `1W` stands for _the first weekday of the month_). +* If the day-of-month field is `LW`, it means _the last weekday of the month_. +* The day-of-week field can be `d#n` (or `DDD#n`), which stands for _the ``n``th day of week `d` +(or ``DDD``) in the month_. + +Here are some examples: + +|=== +| Cron Expression | Meaning + +|`0 0 * * * *` | top of every hour of every day +|`*/10 * * * * *` | every ten seconds +| `0 0 8-10 * * *` | 8, 9 and 10 o'clock of every day +| `0 0 6,19 * * *` | 6:00 AM and 7:00 PM every day +| `0 0/30 8-10 * * *` | 8:00, 8:30, 9:00, 9:30, 10:00 and 10:30 every day +| `0 0 9-17 * * MON-FRI`| on the hour nine-to-five weekdays +| `0 0 0 25 DEC ?` | every Christmas Day at midnight +| `0 0 0 L * *` | last day of the month at midnight +| `0 0 0 L-3 * *` | third-to-last day of the month at midnight +| `0 0 0 * * 5L` | last Friday of the month at midnight +| `0 0 0 * * THUL` | last Thursday of the month at midnight +| `0 0 0 1W * *` | first weekday of the month at midnight +| `0 0 0 LW * *` | last weekday of the month at midnight +| `0 0 0 ? * 5#2` | the second Friday in the month at midnight +| `0 0 0 ? * MON#1` | the first Monday in the month at midnight +|=== + +==== Macros + +Expressions such as `0 0 * * * *` are hard for humans to parse and are, therefore, hard to fix in case of bugs. +To improve readability, Spring supports the following macros, which represent commonly used sequences. +You can use these macros instead of the six-digit value, thus: `@Scheduled(cron = "@hourly")`. + +|=== +|Macro | Meaning + +| `@yearly` (or `@annually`) | once a year (`0 0 0 1 1 *`) +| `@monthly` | once a month (`0 0 0 1 * *`) +| `@weekly` | once a week (`0 0 0 * * 0`) +| `@daily` (or `@midnight`) | once a day (`0 0 0 * * *`), or +| `@hourly` | once an hour, (`0 0 * * * *`) +|=== + + [[scheduling-quartz]] === Using the Quartz Scheduler