The TimerService.getTimers( ) method can throw an IllegalStateException or an EJBException. All of the createTimer( ) methods declare these two exceptions, plus a third exception, the IllegalArgumentException. The reasons that the TimerService methods would throw these exceptions are:

The previous section used the Timer.cancel( ) method. It’s used to cancel a specific timer: remove the timed event from the Timer Service so that it never expires. It is useful if a particular timer needs to be removed completely or simply rescheduled. To reschedule a timed event, cancel the timer and create a new one. For example, when one of the ship’s components fails and is replaced, that component must have its maintenance rescheduled: it doesn’t make sense to perform a yearly overhaul on an engine in June if it was replaced in May. The scheduleMaintenance( ) method can be modified so that it can add a new maintenance item or replace an existing one by canceling it and adding the new one.

 public abstract class ShipBean 
      implements javax.ejb.EntityBean, javax.ejb.TimedObject {
    javax.ejb.EntityContext ejbContext;
    public void setEntityContext(javax.ejb.EntityContext ctxt){
         ejbContext = ctxt;
    }
    public void scheduleMaintenance(String description, Date dateOfTest){
                     TimerService timerService = ejbContext.getTimerService( );
                     java.util.Iterator timers = timerService.getTimers( ).iterator( );
                     while( timers.hasNext( ) ){
                     javax.ejb.Timer timer = (javax.ejb.Timer) timers.next( );
                     String timerDesc = (String) timer.getInfo( );
                     if( description.equals( timerDesc)){
                     timer.cancel( );
                     }
                     }
                     timerService.createTimer( dateOf, description);
                     }
    public void ejbTimeout(javax.ejb.Timer timer) {
       // business logic for timer goes here
    }
    ...

The scheduleMaintenance( ) method first obtains a Collection of all timers defined for the Ship. It then compares the description of each timer to the description passed into the method. If there is a match, it means a timer for that maintenance item was already scheduled and should be canceled. After the while loop, the new Timer is added to the Timer Service.

Of course, comparing descriptions is a fairly unreliable way of identifying timers, since descriptions tend to vary over time. What is really needed is a far more robust information object that can contain both a description and a precise identifier.

All of the TimeService.createTimer( ) methods declare an info object as their last parameter. The info object is application data that is stored with by the Timer Service and delivered to the enterprise bean when its ejbTimeout( ) method is called. The serializable object used as the info parameter can be anything, as long it implements the java.io.Serializable interface and follows the rules of serialization.^[44] The info object can be put to many uses, but one obvious use is to associate the timer with some sort of identifier.

To get the info object from a timer, call the timer’s getInfo( ) method. This method returns a serializable object, which you’ll have to cast to an appropriate type. So far, we’ve been using strings as info objects, but there are much more elaborate (and reliable) possibilities. For example, rather than compare maintenance descriptions to find duplicate timers, Titan decided to use unique Maintenance Item Numbers (MINs). MINs and maintenance descriptions can be combined into a new MaintenanceItem object:

public class MaintenanceItem implements java.io.Serializable {
    private long maintenanceItemNumber;
    private String description;
    public MaintenanceItem(long min, String desc){
        maintenanceItemNumber = min;
        description = desc;
    }
    public long getMIN( ){
        return maintenanceItemNumber;
    }
    public String getDescription( ){
        return description;
    }
}

Using the MaintenanceItem type, we can modify the scheduleMaintenance( ) method to be more precise, as shown below (changes are in bold):

public abstract class ShipBean 
      implements javax.ejb.EntityBean, javax.ejb.TimedObject {
    javax.ejb.EntityContext ejbContext;
    public void setEntityContext(javax.ejb.EntityContext ctxt){
         ejbContext = ctxt;
    }
    public void scheduleMaintenance(
      MaintenanceItem maintenanceItem, Date dateOfTest){
        TimerService timerService = ejbContext.getTimerService( );
        java.util.Iterator timers = timerService.getTimers( ).iterator( );
        while( timers.hasNext( ) ){
                javax.ejb.Timer timer = (javax.ejb.Timer) timers.next( );
                MaintenanceItem timerMainItem = (MaintenanceItem) timer.getInfo( );
                     if( maintenanceItem.getMIN( ) == timerMainItem.getMIN( )){
                     timer.cancel( );
                   }
        }
        timerService.createTimer( dateOf, maintenanceItem);
    }
    public void ejbTimeout(javax.ejb.Timer timer) {
       // business logic for timer goes here
    }
    ...

The MaintenanceInfo class contains information about the maintenance work that is to be done and is sent to the maintenance system using JMS. When one of the timers expires, the Timer Service calls the ejbTimeout( ) method on the Ship EJB. When the ejbTimeout( ) method is called, the info object is obtained from the Timer object and used to determine which timer logic should be executed.

Exercise 13.1 in the Workbook shows how to deploy these examples in JBoss.

The Timer.getNextTimeout( ) method simply returns the date—represented by a java.util.Date instance—on which the timer will expire next. If the timer is a single-action timer, the Date returned is the time at which the timer will expire. If, however, the timer is an interval timer, the Date returned is the time remaining until the next expiration. Oddly, there is no way to determine subsequent expirations or the interval at which an interval timer is configured. The best way to handle this is to put that information into your info object.

The Timer.getTimeRemaining( ) method returns the number of milliseconds before the timer will next expire. Like the getNextTimeout( ) method, this method only provides information about the next expiration.

The Timer.getHandle( ) method returns a TimerHandle. The TimerHandle is similar to the javax.ejb.Handle and javax.ejb.HomeHandle discussed in Chapter 5. It’s a reference that can be saved to a file or some other resource, then used later to regain access to the Timer. The TimerHandle interface is simple:

package javax.ejb;
public interface TimerHandle extends java.io.Serializable {
    public Timer getTimer( ) throws NoSuchObjectLocalException, EJBException;
}

The TimerHandle is only valid as long as the timer has not expired (if it’s a single-action timer) or been canceled. If the timer no longer exists, calling the TimerHandle.getTimer( ) method throws a javax.ejb.NoSuchObjectException.

TimerHandle objects are local, which means they cannot be used outside the container system that generated them. Passing the TimerHandle as an argument to a remote or endpoint interface method is illegal. However, a TimerHandle can be passed between local enterprise beans using their local interface, because local enterprise beans must be co-located in the same container system.

All the methods defined in the Timer interface declare two exceptions: