1. Introduction
In this tutorial, we’ll learn how to use the @Scheduled annotation in Spring with cron expressions.
The cron expression used in Spring is slightly different from the unix cron expression, as it requires an additional field. Which might confuse some of us regarding the use of the sixth field.
Let’s start by understanding the different cron expression types and then learn how to configure the @Scheduled annotation in Spring.
2. Standard Cron Expression Format
In Unix-based systems and most online cron expression tools, cron expressions typically consist of five fields separated by spaces:
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday; 7 is also Sunday)
│ │ │ │ │
│ │ │ │ │
* * * * * command to execute
Each field represents a specific unit of time and can contain values in the range in parenthesis. For example, we can write a cron expression to indicate to run a job every Friday at 6 PM:
0 18 * * 5
Here, the asterisks represent “every” value so that this expression will run the job at 6 PM every Friday.
Plugging this cron expression in @Scheduled won’t even start our Spring application as it requires a different format. Let’s see how we can use the @Scheduled annotation in Spring.
3. Using @Scheduled Annotation in Spring
To configure a task to run at a specific time or interval in a Spring application, we can use the @Scheduled annotation along with a cron expression:
@Scheduled(cron = "0 0 18 * * 5")
public void scheduledTask() {
// Task logic here
}
Similarly, the cron expression in this example will run the scheduledTask() method every Friday at 6 PM. We can see that the format is similar to the standard cron expression, but it requires an additional field.
So, Spring extends the standard format by adding a sixth parameter at the beginning to represent seconds:
┌───────────── second (0 - 59)
│ ┌───────────── minute (0 - 59)
│ │ ┌───────────── hour (0 - 23)
│ │ │ ┌───────────── day of the month (1 - 31)
│ │ │ │ ┌───────────── month (1 - 12)
│ │ │ │ │ ┌───────────── day of the week (0 - 7) (0 and 7 both represent Sunday)
│ │ │ │ │ │
* * * * * *
Having a finer-grained control over task scheduling allows to control cron jobs down to the second level. However, it’s worth noting that system load can heavily influence the actual execution time of the scheduled tasks.
We must note that to enable scheduling in Spring, we need to add @EnableScheduling annotation to our configuration class.
Cron expressions are very flexible and become even more powerful when combined with special characters. Let’s have an overview of these special characters.
4. Special Characters in Cron Expressions
Just like in standard cron syntax, Spring cron expressions support special characters to provide more flexibility.
We can use the asterisk * to represent all possible values for a field. Alternatively, we can use a question mark ? to represent no specific value, typically used for “day of the month” or “day of the week”.
For example, to run a task at the start of each hour every day of the week:
@Scheduled(cron = "0 0 * * * ?")
We can also specify multiple values using a comma or a range of values using a hyphen -. Additionally, we can use the forward slash / to specify increments.
For example, to run a task every 2 hours on Saturday and Sunday between the first and the 15th day of the month:
@Scheduled(cron = "0 0 0/2 1-15 * 6,7")
As we can see from the last example, we can combine multiple special characters to create complex scheduling patterns.
5. Conclusion
In this article, we learned about Cron expression in Spring and how to use it with the @Scheduled annotation. First, we looked at the standard Unix cron expression format and then saw how Spring extends it by adding a sixth parameter for seconds. Finally, we explored how to use special characters to create complex scheduling patterns.