EJB Timer Service

Internal

• EJB Concepts

Overview

The EJB timer service is a container-provided service that creates timers programmatically or declaratively, and that invokes time-based callbacks into EJBs.

Timer Service

The timer service is a container-provided service that can be used to programmatically create, and then can be relied on to invoke, timers. Timers can also be created declaratively without the need to get a reference to the timer service. The callbacks can be invoked according to a calendar-based schedule, at a specified time, after a specified elapsed time, or at specified intervals. The timer service is a coarse-grained notification service that is not intended to model real-time events. The callback invocations, and also those of methods used to create and cancel timers typically occur in a transactional context. For more details see Transactions. The methods do not have client security context. For more details see Security. The timer service durations are expressed in milliseconds. The timer service is intended to serve long-lived business processes, timers survive container crashes, server shutdown and activation/passivation/load/store cycle of the EJBs that are registered with them.

Access

An EJB may access the timer service via dependency injection, by calling EJBContext.getTimerService() on the EJBContext interface or by looking it up in JNDI.

API

The timer service interface is specified by javax.ejb.TimerService.

Timer

A timer is an object created to schedule a timed callback. Timers can be created automatically (declaratively) by the EJB container at deployment based on the bean class or deployment descriptor metadata. Timers can also be created and canceled programmatically, and the timers that are associated with a bean can be located programmatically. Timers can be created by stateless session beans, singleton beans, message driven beans. They cannot be create for stateful session beans. The callback method invocation for a stateless session bean or a message-driven bean timer may be called on any bean instance in the pooled state.

The EJB class that uses the timer service must provide one or more timeout callbacks. When the time specified at timer creation elapses, the container invokes the associated timeout callback method of the bean.

For programmatically created timers, a timeout callback is a method annotated with the @Timeout annotation, or if the bean implements javax.ejb.TimedObject interface, the implementation of the ejbTimeout() method. For timers that are declared, the timeout method is any method annotated with the @Schedule annotation.

A timer may be cancelled by a bean before its expiration by calling its cancel() method.

Client-specific information may be passed at timer creation (programmatic or declarative) to help recognize the significance of the timer’s expiration. The information object must be serializable.

Automatic Timer Creation

Timers are automatically created based on metadata in the bean class or deployment descriptor. This allows a developer to schedule a timer without relying on a bean invocation to programmatically invoke one of the Timer Service timer creation method. @Schedule and @Schedules annotations can be used for that.

By default, each @Schedule annotation corresponds to a single persistent timer, regardless of the number of JVMs across which the container is distributed.

Example:

@Schedule(hour="3", dayOfMonth="1", info="something")
public void toBeExecutedAt3AMOnTheFirstDayOfTheMonth() {
   ...
}

Multiple timers can be applied using the @Schedules annotation:

@Schedules(
{
    @Schedule(hour="3", dayOfWeek="Mon-Thu"),
    @Schedule(hour="4", dayOfWeek="Fri")
})
public void something() {
   ...
}

For more details on the @Schedule annotation configuration syntax, see:

@Schedule Configuration

Programmatic Timer Creation

The API allows programmatic creations of single-event timers, interval timers or a calendar schedule-based timers. The timer creation methods return a Timer object that allows cancellation or obtaining information about the timer. By default, programmatically created timers are persistent. A non-persistent timer can be created by calling setPersistent(false) on a TimerConfig object passed to a timer creation method.

For single-event and interval timers, expiration may be expressed as duration in milliseconds or absolute time.

For calendar timers, the schedule is built via a ScheduleExpression instance using a builder pattern.

ScheduleExpression schedule = new ScheduleExpression().dayOfWeek("Sat").hour(1);
Timer timer = timerService.createCalendarTimer(schedule);

Persistent Timer

Timers are persistent by default, they survive application server, crashes, activation and passivation of EJB instances.

Non-Persistent Timer

A non-persistent timer is a timer whose lifetime is tied to the JVM in which it was created: it is cancelled by application shutdown or container crash.

The non-persistent timers are created by setting the "persistent" attribute of the @Schedule annotation to "false".

Timeout Callback

An EJB that is registered with a Timer must provide timeout callback methods. There are two types of callback methods:

Timeout callback for timers that are created programmatically. They use a single timeout callback method, which must be annotated with @Timeout, implement ejbTimeout() of the javax.ejb.TimedObject interface, or be declared as "timeout-method" in the deployment descriptor. An EJB must have at most one timeout callback for programmatic timers.

Timeout callback for timers that are declared (automatically created). They use methods annotated with @Schedule/@Schedules annotations. For more details on how the annotation should be used with methods, and what methods are allowed, see:

@ Schedule Usage Rules

The container interleaves calls to timeout callbacks with calls to business methods and lifecycle callbacks, so the time at which a timeout callback is called may occur after the timer fired. If multiple timers fire at approximately the same time, callbacks may be out of sequence.

Transactions

Timers are created and canceled in a transaction, if the transaction is rolled back, the timer creation or cancellation is rolled back.

The timer callback invocation take place in the transactional context the bean has requested via declaration.

Security

Timeout callback methods are internal calls, so they do not have a client security context.