Oracle® Fusion Middleware

TimerManager Interface

The TimerManager interface provides the general scheduling framework within an application. A managed environment can support multiple TimerManager instances. Within an application you can have multiple instances of a TimerManager.

The TimerListener Interface

All applications using the commonj.timers package are required to implement the TimerListener interface.

The Timer Interface

Instances of the Timer interface are returned when timers are scheduled through the TimerManager.

Implementing the Timer API

To implement the Timer API, complete the following steps:

1. Import the commonj.timers.* packages.

2. Create an InitialContext that allows the TimerManager to be looked up in JNDI. For example:

   InitialContext inctxt = new InitialContext(); 
   

   See Programming JNDI for Oracle WebLogic Server for more information about JNDI lookup.

3. Create a new TimerManager based on the JNDI lookup of the TimerManager. For example:

   TimerManager mgr = (TimerManager)ctx.lookup('java:comp/env/timer/MyTimer');
   

   In this statement, the result of the JNDI lookup is cast to a TimerManager.

4. Implement a TimerListener to receive timer notifications. For example:

   TimerListener listener = new StockQuoteTimerListener('abc', 'example');
   

5. Invoke the TimerManager.schedule method. For example:

   mgr.schedule(listener, 0, 1000*60)
   

   The schedule method returns a Timer object.

6. Implement the timerExpired method. For example:

   public void timerExpired(Timer timer) {
        //Business logic is executed
        //in this method
   }
   

Implementing the Timer API for cluster-wide timers has additional requirements, described in Life Cycle of Timers.

Timer Manager Example

package examples.servlets;
import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import commonj.timers.*;

/**
* TimerServlet demonstrates a simple use of commonj timers
*/
public class TimerServlet extends HttpServlet {

/**
  * A very simple implementation of the service method,
  * which schedules a commonj timer.
  */
  public void service(HttpServletRequest req, HttpServletResponse res)
    throws IOException
  {
    res.setContentType("text/html");
    PrintWriter out = res.getWriter();
    try {
      InitialContext ic = new InitialContext();
      TimerManager tm = (TimerManager)ic.lookup
        ("java:comp/env/tm/default");
      // Execute timer every 10 seconds starting immediately
      tm.schedule (new MyTimerListener(), 0, 10*1000);
      out.println("<h4>Timer scheduled!</h4>");
    } catch (NamingException ne) {
      ne.printStackTrace();
      out.println("<h4>Timer schedule failed!</h4>");
    }
  }

  private static class MyTimerListener implements TimerListener {
    public void timerExpired(Timer timer) {
      System.out.println("timer expired called on " + timer);
      // some useful work here ...
      // let's just cancel the timer
      System.out.println("cancelling timer ...");
      timer.cancel();
    }
  }
}

Life Cycle of Timers

When you implement the commonj.timer API within an application, you can configure two possible life cycles for a timer:

• Local timer

  A local timer is scheduled within a single server JVM and is handled within this JVM throughout its life cycle. The timer continues running as long as the JVM is running and fails when the JVM exits. The application is responsible for rescheduling the timer after server startup.

  This is the basic implementation of the commonj.timers package.

• Cluster-wide timer

  A cluster-wide timer is aware of the other JVMs containing each server within the cluster and is therefore able to perform load balancing and failover. The life cycle of a cluster-wide timer is not bound to the server that created it, but continues to function throughout the life cycle of the cluster. If at least one cluster member is alive, the timer continues to function. This functionality is referred to as the Job Scheduler.

  Implementing the Timer API for a Job Scheduler has the following requirements in addition to those listed in Implementing the Timer API:

  • The Timer Listener class must be serializable.

  • The Timer Listener class must be present in the server system classpath.

  • The minimum time for recurring execution of a timer is 30 seconds because Job Schedulers pick up timers for execution every 30 seconds.

Each timer has its own advantages and disadvantages. Local timers can process jobs with much smaller time intervals between jobs. Due to the persistence requirements within a cluster, Job Schedulers cannot handle jobs with as much precision. On the other hand, Job Schedulers are better suited for tasks that must be performed even if the initial server that created the task has failed.

Implementing and Configuring Job Schedulers

This section describes the basic procedure for implementing Job Schedulers within an application and for configuring your WebLogic Server environment to utilize them. The following topics are included:

• Database Configuration

• Data Source Configuration

• Leasing

• JNDI Access within a Job Scheduler

• Canceling Jobs

• Debugging

WL_HOME/server/db/dbname/scheduler.ddl

<domain>
...
 <cluster>
  <name>Cluster-0</name>
  <multicast-address>239.192.0.0</multicast-address>
  <multicast-port>7466</multicast-port>
  <data-source-for-job-scheduler>JDBC Data     Source-0</data-source-for-job-scheduler>
 </cluster>
...
 <jdbc-system-resource>
  <name>JDBC Data Source-0</name>
  <target>myserver,server-0</target>
  <descriptor-file-name>jdbc/JDBC_Data_Source-0-3407-jdbc.xml</descriptor-file-name>
 </jdbc-system-resource>
</domain>

WL_HOME/server/db/dbname/leasing.ddl

InitialContext ic = new InitialContext(); 
commonj.timers.TimerManager jobScheduler =(common.timers.TimerManager)ic.lookup
   ("weblogic.JobScheduler");
commonj.timers.TimerListener timerListener = new MySerializableTimerListener();
jobScheduler.schedule(timerListener, 0, 30*1000); 
// execute this job every 30 seconds

-Dweblogic.debug.DebugSingletonServices=true -Dweblogic.JobScheduler=true

Unsupported Methods and Interfaces

The following methods and interfaces in the commonj.timer package are not supported in the Job Scheduler environment:

• CancelTimerListener interface

• StopTimerListener interface

• The following methods of the TimerManager interface:

  • suspend

  • resume

  • scheduleAtFixedRate

  • stop

  • waitForStop

  • waitForSuspend

Work Manager Interfaces

This section summarizes the interfaces in the Work Manager API. For details about using these interfaces, see commonj.work in the Oracle WebLogic Server API Reference.

The Work Manager API contains the following interfaces:

• WorkManager - Provides a set of scheduling methods that are used to schedule work for execution.

  A WorkManager is defined by system administrators at the server level. A WorkManager instance is obtained by performing a JNDI lookup. A managed environment can support multiple WorkManager instances. You configure WorkManagers during deployment as resource-refs. See Work Manager Deployment.

  At the application level, each instance of WorkManager returns a WorkItem. For more information about implementing a WorkManager within an application, see WorkManager in the Oracle WebLogic Server API Reference.

  For information about JNDI, see Programming JNDI for Oracle WebLogic Server.

• Work - Allows you to run application code asynchronously. By creating a class that implements this interface, you can create blocks of code that can be scheduled to run at a specific time or at defined intervals. In other words, this is the "work" that is handled within the Work Manager API.

• WorkItem - Determines the status of a completed Work instance. A WorkItem is returned by a WorkManager after a Work instance has been submitted to that WorkManager.

  For more information, see Work in the Oracle WebLogic Server API Reference.

• WorkListener - Provides communication between the WorkManager and the scheduled work defined within the Work instance. WorkListener is a callback interface.

  You can use WorkListener to determine the current status of the Work item. For more information, see WorkListener in the Oracle WebLogic Server API Reference.

  Note:

  WorkListener instances are always executed in the same JVM as the original thread used to schedule the Work by means of the WorkManager.

• WorkEvent - A WorkEvent is sent to a WorkListener as Work is processed by a WorkManager.

  For more information, see WorkEvent in the Oracle WebLogic Server API Reference.

• RemoteWorkItem - The RemoteWorkItem interface is an extension of the WorkItem interface that allows work to be executed remotely. This interface allows serializable work to be executed on any member of a cluster.

  For more information, see RemoteWorkItem in the Oracle WebLogic Server API Reference.

Work Manager Deployment

Work Managers are defined at the server level by means of a resource-ref in the appropriate deployment descriptor. This can be web.xml or ejb-jar.xml, among others.

The following deployment descriptor snippet shows the configuration of a WorkManager:

...
<resource-ref>
   <res-ref-name>wm/MyWorkManager</res-ref-name>
   <res-type>commonj.work.WorkManager</res-type>
   <res-auth>Container</res-auth>
   <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
...