Monday, 24 February 2014

Understanding EJB Timer Service 3.1

EJB Timer Service - Introduction

Timer service was introduced in EJB 2.1 for J2EE applications that requires scheduling service. Configuring an EJB Timer service became more easy with introduction of annotations in EJB 3.0.

But there was something lacking in the EJB Timer versions in 2.1 and 3.0. That was the crone job like support for scheduling which allows creation of scheduled task for a particular day/days of every week or task for a particular date in a month every year. Precisely initial EJB Timer versions didn't had calendar based scheduling. These versions supported only Single Action timers which execute its task on the mentioned time for a single time and a fixed interval timer which repeats after fixed interval after the first execution.

Timer Service in EJB 3.1

EJB 3.1 came up with javax.ejb.ScheduleExpression which supports calendar based time out expression just like a crone job. This makes EJB Timer service much more useful with advanced scheduling options. This helps in simple designing of your scheduling application with necessary advanced features.

Usage of calendar based chrone job like timer ScheduleExpression supports the below attributes:
  1. second - Allowed values [0,59]. Attribute can be specified as a single scheduler value or a list of values or a range of values. Examples are as follows:
    • Single value - scheduleExpression.second("10");
    • List of values - scheduleExpression.second("10,20");
    • Range of values - scheduleExpression.second("0-10");
    • Range + list of values - scheduleExpression.second("0-10,20,30");
    • Repeating iteration of scheduler can be specified using a forward slash. 
      • scheduleExpression.second("*/10" (Every 10 seconds within the minute);
  2. minute - Allowed values [0,59]. Attribute can be specified for scheduling in the same way as that of second. Example for repeating iteration: scheduleExpression.minute("*/5"); (Every five minutes within the hour)
  3. hour  - Allowed values [0,23]. Attribute can be specified for scheduling in the same way as that of second. Example for repeating iteration: scheduleExpression.hour("*/2); (Repeat execution in every 2 hours duration of the day.)
  4. dayOfMonth - Allowed values:
    • [1,31]
    • "Last" means the last day of the month
    • {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
    • {"1st", "2nd", "3rd", "4th", "5th", "Last"}
    • -x (where x is in the range [-7, -1]) means x day(s) before the last day of the month
  5. month - Allowed values:
    • [1,12]
    • {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", Dec"}
  6. dayOfWeek - Allowed values:
    • [0,7] - "0" and "7" both refer to Sunday
    • {"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"}
  7. year - Any four digit year greater than or equal to current year is allowed.
Please refer to javadoc of ScheduleExpression for the detailed usage.

EJB Timer Service in Multi-Server environments:

Production environment of most of the applications would be a multi-server environment. Handling of an EJB Timer in a multi-server environment is crucial for the successful usage of an EJB Timer as your application's scheduler. Following are the two possible timer configurations in a multi-server environment.

  1. Shared timer service across multiple servers: This configuration allows any server process to create or access the timer service. That means a timer service created by one server process can be found in another server using getTimers(). The server which obtains lock on common internal EJB Timer tables executes all the timers. If the server executing timers goes down, then another server will take over and begins execution of the timers at the scheduled time. This is the recommended configuration for all the applications. 
  2. Separate timer service database per server instance: This is the default timer service configuration. This configuration allows only the server instance that created the timer service to allow the access of the timer service. This means that if the server instance that created the timer service is unavailable, then the timer will not get executed. This configuration can be used for single server environments.
EJB 3.1 supports programmatic timers and automatic timers.

Programmatic Timers:

Programmatic EJB timers are created by using the create methods of the TimerService interface. Programmatic Timer should have a method annotated with @Timeout that returns void and can optionally have Timer object as its single parameter. This is the method where the business logic that needs to be executed on timer expiration is specified.

Following TimerService methods can be used for creating a programmatic timer:
  • createCalendarTimer - Calendar based Timer using schedule expression discussed earlier.
  • createIntervalTimer - Creates a repeating timer whose first execution point and the interval for subsequent execution points can be defined.
  • createSingleActionTimer - creates a single-action timer.
  • createTimer - Has overloading methods to support interval timer and single action timer.
Refer to javadoc of TimerService API for detailed usage of timer service methods.
Timers are persistent by default and hence won't be affected by a server crash. If the timer was supposed to start execution when the server was down, then it would be executed as soon as server is up again.

Automatic Timers:

Automatic timers are created and scheduled on deployment automatically based on @Schedule or @Schedules annotation. This can be used for applications which do purging or do End of Day kind of processing on application's predefined interval.
Example of EJB 3.1 Automatic Timer can be found here

Automatic timer can have multiple methods for timeout with relevant Schedule annotation whereas programmatic timers can have only one @Timeout method.

Transactions in EJB Timer:
If you are trying to do a JPA operation on your entity, please do it in a separate session bean and call it from your timer. Otherwise, you will end up with transaction management issues,