Automatic Timers

The container invokes any method appropriately annotated with @Schedule and applies the schedule configuration specified in the annotation’s attributes. The attributes of the annotation are set following the calendar-based timer attributes in the “Timer Expression” section that follows. Here is a simple example:

@Schedule(second="*/1", minute="*", hour="*")
public void executeTask(){
    System.out.println("Task performed");
}

In this code snippet, the method executeTask is annotated @Schedule; this indicates to the container to set a timer upon deployment based on the time values specified in the annotations attributes. In this example the container invokes the executeTask method once every second.

By default, all timers are persisted and restored after a server shutdown or crash. If you set the optional attribute persistent to false, the timer is reset on server restart. You can set two additional attributes: info and timezone. If you set timezone, that time zone is respected when executing the timer; otherwise, the server time zone is used. The info attribute allows a developer to provide a description of the time that you can retrieve by calling the getInfo method of the Timer interface.

@Schedule(hour = "23", minute = "59", timezone = "CET",
          info = "Generates nightly report")
public void executeTask(){
    System.out.println("Task performed");
}

In the preceding code snippet, the executeTask method is invoked at 23:59 Central European time regardless of the time zone of the server on which it is deployed. A call to the method getInfo returns the text Generates nightly report.

You can configure more complex timers using @Schedules (note the pluralization) with multiple timer expressions.

@Schedules({
    @Schedule(dayOfMonth = "1"),
    @Schedule(dayOfWeek = "Mon,Tue,Wed,Thu,Fri", hour = "8")
})
public void executeTask() {
    System.out.println("Task performed");
}

This timer fires on the first of every month and every work day at 08:00. Listing 10-1 shows a complete example of an automatic timer.

One drawback of the automatic timer is that its schedule is set at deployment time and cannot be changed while the application is executing. Fortunately, there is a solution to this situation in the form of the programmatic timer, which you can set at any moment during run time.

Programmatic Timers

Programmatic timers are created at run time by invoking one of the create methods of the TimerService interface. Here is a simple example:

public void setTimer(){
    timerService.createTimer(30000, "New timer");
}

When the application code invokes the setTimer method, it creates a single-action timer that calls a “timeout” method in the same bean after the specified duration of 30,000 milliseconds. A “timeout” method is identified by the annotation @Timeout and must conform to certain requirements. It must not throw exceptions or return a value. It’s also exempt from needing to take a parameter, but if it does, it must be of type javax.ejb.Time. There can be only one “timeout” method.

@Timeout
public void performTask() {
    System.out.println("Simple Task performed");
}

The Context Dependency Injection (CDI) container injects a reference to the TimerService into an instance variable annotated @Resource. Here the container injects the instance variable timerService.

@Resource
TimerService timerService;

If you put together the previous three code snippets into a single bean and the application code calls the setTimer method, you create a timer that, after 30 seconds, calls the “timeout” method performTask. Listing 10-2 shows the simplest possible implementation of the programmatic timer in Java EE 7.

There are four timer creation methods in the TimerService interface with ten signatures. Table 10.2 shows an example of each one:

All methods apart from the createCalendarTimer method can take as the first parameter either duration in milliseconds or a date. This sets up the point at which the timer is triggered. Here is an example:

SimpleDateFormat formatter = new SimpleDateFormat("dd/MM/yyyy 'at' HH:mm");
Date date = formatter.parse("26/01/2015 at 17:56");
timerService.createSingleActionTimer(date, new TimerConfig());

In this code snippet, the “timeout” method is triggered at 17:56 on January 26, 2015.

If a scheduled timer is required, you can use the createCalendarTimer method. This method takes a ScheduleExpression object in which a schedule is set using the values described in the “Timer Expression” section that follows.

ScheduleExpression expression = new ScheduleExpression();
expression.second("*/10").minute("*").hour("*");
timerService.createCalendarTimer(expression);

In this code snippet, the schedule is set to trigger every ten seconds of every minute of every hour.

All the creation methods return a Timer object that represents the timer. This object has the method getHandle, which returns a serializable handle to the timer. The handle object can be persisted in a database or memory.

Later you can retrieve the handle object and return a reference to the timer by invoking the getTimer method. With this object in hand, you can retrieve useful information about the timer.

It’s easy to obtain information about the behavior of the timer. You can retrieve details regarding the timer’s schedule by calling the method getSchedule. This returns a ScheduleExpression object that has a getter method for each attribute. For example, getMinute() returns the value set for the minute attribute. The getNextTimeout method gets the point when the timer fires next, whereas the method getTimeRemaining returns the milliseconds before the timer expires.

The isCalendarTimer method returns true if the timer was set by constructing a ScheduleExpression object. You must call it before the getSchedule method to determine if the timer was set this way; otherwise, isCalendarTimer throws an IllegalStateException exception.

You can determine information about the timer’s persistent state by using the isPersistent method. Similarly, you can obtain information about the time by calling the getInfo method.

Timers are automatically cancelled when they expire. The container cancels the single-event timers, and you can cancel scheduled timers by calling the cancel method on the Timer object.

Timer Expression

Both programmatic and automatic timers can use calendar-based timer attributes. Table 10.3 shows the range of timer attributes that are used to set the timers. For automatic calendar-based timers, you set the calendar attributes in the annotation, whereas programmatic calendar-based timers use methods of the ScheduleExpression class to set the calendar attribute values.

It’s worth noting that the default value for the time attributes is 0 (zero) and for the non-numerical values it is * (asterisk).

This table has been appropriated from the Oracle’s Java EE 7 tutorial.² The syntax is cron-like and should be familiar to most programmers. There are a few interesting characteristics worth pointing out.

The asterisk character is a placeholder for all possible values for the given attribute. For example, to set a schedule to trigger every hour, you would use the expression hour="*" for annotation-configured timers. For programmatic timers, you would invoke the method hour("*")on an instance of the ScheduleExpression class.

You can express values for each attribute as a list or a range. For example, the expression dayOfMonth="1, 15, last" sets the timer to trigger on the first, fifteenth, and last day of every month, whereas the expression hour="8-18" represents every hour from 08:00 until 18:00.

You can specify intervals and augment them with a starting point. The expression hour="8/1" triggers every hour starting from 08:00, whereas the expression hour="*/12" triggers every 12 hours. However, you can only set intervals for seconds, minutes, and hour attributes.

Table 10.4 offers a few examples of the calendar-based schedule in action.

New in the EJB 3.2 implementation is an enhancement to the timer service API that allows access to all active timers in the EJB module. These include both programmatically and automatically created timers.

In Listing 10-3, the bean is instantiated at start-up, and the manageTimer method is called. You retrieve a collection of all the active timers and iterate over the collection, printing out the timer info and the number of milliseconds that will elapse before the next scheduled timer expiration. Finally, you cancel the timer.

Transactions

Beans create timers within a transaction that the container manages. If this transaction is rolled back, so is the timer. If this transaction is rolled back then the timer is also rolled back. This means that its creation is rolled back and if it were canceled the cancellation would be undone and the timer reinstated. In listing 10-4 we show an example of a timer method marked with a transaction annotation.

Beans that use container-managed transactions set the transitions attribute on the method annotated @Timeout. Transactions are designated Required or RequiresNew. The transaction is started before the method is called. If the transaction is rolled back, the @Timeout method is called again.