The scheduler, also called calendar timer, is a particular timer starting after a defined date. Unlike the simple timer, the method needs a special annotation, the @Schedule, to be marked with the timeout. Let's take a sample of the scheduled method:
@Singleton
public class SchedulerBean {
@Schedule(minute = "*/3", hour = "*")
public void automaticTimeout() {
...
}
@Schedule(dayOfWeek = "Sun", hour = "0")
public void cleanupWeekData() {
...
}
...
}
In this sample, the singleton has two scheduled methods.
The first is set to start every three minutes. The used expression to set the time is the syntax of the Unix Cron utilities, by now a standard for all types of timers.
The second will start on each Sunday at midnight. You can find all the configuration params for the schedule annotation in this table:
|
Attribute |
Description |
Default Value |
Allowable values and examples |
|
second |
Number of seconds within a minute |
0 |
From 0 to 59. For example, second="30". |
|
minute |
Number of minutes within an hour |
0 |
From 0 to 59. For example, minute="15". |
|
hour |
Number of hours within a day |
0 |
From 0 to 23. For example, hour="13". |
|
dayOfWeek |
Number of days within a week |
* |
From 0 to 7 (both 0 and 7 refer to Sunday). For example, dayOfWeek="3". Sun, Mon, Tue, Wed, Thu, Fri, and Sat. For example, dayOfWeek="Mon". |
|
dayOfMonth |
Number of days within a month |
* |
From 1 to 31. For example, dayOfMonth="15". From –7 to –1 (a negative number means the nth day or days before the end of the month). For example, dayOfMonth="–3". Last. For example, dayOfMonth="Last". [1st, 2nd, 3rd, 4th, 5th, Last] [Sun, Mon, Tue, Wed, Thu, Fri, Sat]. For example, dayOfMonth="2nd Fri". |
|
month |
Number of months within a year |
* |
From 1 to 12. For example, month="7". Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. For example, month="July". |
|
year |
The calendar year |
* |
A four digit calendar year, for example, year="2011". |
To see whether the timer is set as scheduler, you can use this method for the timer:
Timer timer.....
timer.isCalendarTime();
If it returns true, it is a scheduler; otherwise, it is a timer working with the numeric countdown.
The scheduler can be configured programmatically in the timer in this mode:
ScheduleExpression scheduleExpression = new ScheduleExpression();
scheduleExpression.hour("10");
scheduleExpression.start(new Date());
Timer timer = timerService.createCalendarTimer(scheduleExpression, new TimerConfig());
...
In this sample, we are configuring a scheduler, starting now, at 10 AM.
If the timer is not a scheduler, a java.lang.IllegalStateException will be thrown.
A scheduled method can be configured with multiple expressions using the @Scheduled annotation that holds more schedules. Here's a sample of the multiple scheduled annotated method:
@Schedules({ @Schedule(dayOfMonth = "Last"), @Schedule(dayOfWeek = "Fri", hour = "23") })
public void doPeriodicCleanup() {
...
}
In this case, we are configuring the timer expiring on the last day of each month and each Friday at 11 PM.
A calendar schedule is cumulative; for example, we can add a new schedule expression starting the createCalendarTimer method of the TimeService class again:
...
scheduleExpression = new ScheduleExpression();
scheduleExpression.dayOfWeek("Wed");
timer = timerService.createCalendarTimer(scheduleExpression, new TimerConfig());