Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.5.0)

Part Number E13981-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

Configuring an Enterprise Bean With an OC4J Cron Timer

You can use an OC4J cron timer with the following:

You can schedule a timer to execute regularly at specified intervals. In the UNIX world, these are known as cron timers.

Example 25-3 shows examples of the different methods you can use in scheduling a cron timer. Where there is an asterisk, all values are valid.

Example 25-3 How to Configure Different Cron Timers

20  * * * * --> 20 minutes after every hour, such as 00:20, 01:20, and so on
 5 22 * * * --> Every day at 10:05 P.M.
 0  8 1 * * --> First day of every month at 8:00 A.M. 
 0  8 4 7 * --> The fourth of July at 8:00 A.M. 
15 12 * * 5 --> Every Friday at 12:15 P.M.

The format of a cron time variable includes five time fields, as follows:

You can define complex timers by specifying multiple values in a field, separated by commas or a dash, as Example 25-4 shows.

Example 25-4 Complex Cron Timers

0  8   *   * 1,3,5 --> Every Monday, Wednesday, and Friday at 8:00 A.M.
0  8  1,15 *  *   --> The first and 15th of every month at 8:00 A.M.
0 8-17 *   * 1-5  --> Every hour from 8 A.M. through 5 P.M., Monday through Friday

To configure an enterprise bean with an OC4J cron timer, do the following:

  1. Acquire the oracle.j2ee.ejb.timer.EJBTimerService in one of the following ways:

    • For an EJB 3.0 enterprise bean, use the @Resource annotation, as Example 25-5 shows.

    • For an EJB 3.0 or EJB 2.1 enterprise bean, use EJBContext or InitalContext method getTimerService, as Example 25-6 shows.

  2. Use EJBTimerService method createTimer to create the appropriate type of timer, as Example 25-5 and Example 25-6 show.

    You can use any of the following EJBTimerService methods, all of which return an object of type javax.ejb.Timer and throw IllegalArgumentException and IllegalStateException:

    • createTimer(String cronline, Serializable info)

      Use this method to create an OC4J cron timer that invokes a timeout callback method on the bean by passing in a String cron line, as the following example shows. Use the info argument to pass application information to OC4J: this can be null:

      ...
      import oracle.j2ee.ejb.timer.EJBTimerService;
      import javax.ejb.timer.Timer;
      ...
      @Resource EJBTimerService ets;
      
      String cron = "1 * * * *";
      String info = "";
      Timer et = ets.createTimer(cron, info);
      ...
      
    • createTimer(int minute, int hour, int dayOfMonth, int month, int dayOfWeek, Serializable info) or

      createTimer(int minute, int hour, int dayOfMonth, int month, int dayOfWeek, int year, Serializable info)

      Use this method to create an OC4J cron timer that invokes a timeout callback method on the bean by passing each cron field as a separate argument, as the following example shows. Use the info argument to pass application information to OC4J: this can be null:

      ...
      import oracle.j2ee.ejb.timer.EJBTimerService;
      import javax.ejb.timer.Timer;
      ...
      @Resource EJBTimerService ets;
      
      int min=15;  // minutes
      int hr=13;   // hour (1 PM)
      int dom=28;  // day of month
      int mo=1;    // month (January)
      int dow=3;   // day of week (Wednesday)
      String info = "";
      Timer et = ets.createTimer(min, hr, dom, mo, dow, info);
      ...
      
    • createTimer(String cronline, String className, Serializable info)

      Use this method to create an OC4J cron timer that invokes the specified Java class's main method by passing in a String cron line, as the following example shows. The info argument can be either null or a String[] of parameters to pass to the main method of the class:

      ...
      import mypackage.MyClass;
      import oracle.j2ee.ejb.timer.EJBTimerService;
      import javax.ejb.timer.Timer;
      ...
      @Resource EJBTimerService ets;
      
      String cron = "1 * * * *";
      String info = "";
      Timer et = ets.createTimer(cron, MyClass.class.getName(), info);
      ...
      
    • createTimer(int minute, int hour, int dayOfMonth, int month, int dayOfWeek, String className, Serializable info) or

      createTimer(int minute, int hour, int dayOfMonth, int month, int dayOfWeek, int year, String className, Serializable info)

      Use this method to create an OC4J cron timer that invokes the specified Java class's main method by passing each cron field as a separate argument, as the following example shows. The info argument can be either null or a String[] of parameters to pass to the main method of the class:

      ...
      import mypackage.MyClass;
      import oracle.j2ee.ejb.timer.EJBTimerService;
      import javax.ejb.timer.Timer;
      ...
      @Resource EJBTimerService ets;
      
      int min=15;  // minutes
      int hr=13;   // hour (1 PM)
      int dom=28;  // day of month
      int mo=1;    // month (January)
      int dow=3;   // day of week (Wednesday)
      String info = "";
      Timer et = ets.createTimer(min, hr, dom, mo, dow,
                                 MyClass.class.getName(), info);
      ...
      

    When you create a Timer on an EJB 2.1 entity bean, the container invokes the timeout callback method of that particular entity bean instance identified by its primary key. Timers created for a particular entity bean are removed when the entity bean is removed.

    When you create a Timer on any other type of EJB, the container invokes the timeout callback method on any instance of that type in the pooled state.

  3. Complete the configuration depending on what action OC4J takes when the timer fires, as follows:

    1. If you created a timer using a createTimer method that does not take a Class, OC4J invokes a timeout callback method when the timer fires.

      The timeout callback method must not be static or final, and must have the following signature:

      void <METHOD>(Timer timer)
      

      You can implement a timeout callback method in one of the following ways:

      • For an EJB 3.0 enterprise bean, annotate any bean method using the @Timeout annotation, as Example 25-5 shows.

      • For an EJB 3.0 or EJB 2.1 enterprise bean, implement the javax.ejb.TimedObject interface, as Example 25-6 shows.

    2. If you created a timer using a createTimer method that takes a Class, OC4J invokes the main method of the Class that you specify when the timer fires.

      The main method must have the following signature:

      public static void main(String args[])
      

Example 25-5 Configuring an OC4J Cron Timer on an EJB 3.0 Stateless Session Bean

import javax.ejb.Stateless;
import javax.annotation.PostConstruct;
import oracle.j2ee.ejb.timer.EJBTimerService;
import javax.ejb.Timer;
import javax.ejb.Timeout;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;

@Stateless
public class MySession {
    @PostConstruct
    @TransactionAttribute(value=REQUIRES_NEW)
    public void initialize() {
        @Resource EJBTimerService ets;
        
        String cron = "1 * * * *";
        String info = "";
        Timer et = ets.createTimer(cron, info);
    }

    ...

    @Timeout
    @TransactionAttribute(value=REQUIRES_NEW)
    public void timeoutCallback(Timer timer) {
    ...
    }
}

Example 25-6 Configuring an OC4J Cron Timer on an EJB 2.1 Stateless Session Bean

import javax.ejb.SessionBean;
import oracle.j2ee.ejb.timer.EJBTimerService;
import javax.ejb.TimedObject;

public class MySession implements SessionBean, TimedObject {
    public void initialize() {
        String cron = "1 * * * *";
        String info = "";
        InitialContext ctx = new InitialContext();
        EJBTimerService ets = (EJBTimerService) ctx.getTimerService();
        Timer et = ets.createTimer(cron, info);
    }
    ...
    public void ejbTimeout(Timer timer) {
    ...
    }
}