Listening for Scheduler Events

The org.quartz.SchedulerListener interface contains a set of callback methods that the Scheduler invokes when key events take place during the life cycle of a Scheduler. Listing 7.9 shows the methods that are included in the SchedulerListener interface.

Listing 7.9. The Methods in the `org.quartz.SchedulerListener` Interface

public interface SchedulerListener {
    public void jobScheduled(Trigger trigger);
    public void jobUnscheduled(String triggerName, String triggerGroup);
    public void triggerFinalized(Trigger trigger);
    public void triggersPaused(String triggerName, String triggerGroup);
    public void triggersResumed(String triggerName,String triggerGroup);
    public void jobsPaused(String jobName, String jobGroup);
    public void jobsResumed(String jobName, String jobGroup);
    public void schedulerError(String msg, SchedulerException cause);
    public void schedulerShutdown();
}

As you can see from the methods listed in Listing 7.9, the SchedulerListener is notified when events occur at the Scheduler level, whether it's the addition or removal of a job in the Scheduler or if the Scheduler encounters a serious error. These events are more about the management of the Scheduler than a particular job or trigger.

The `jobScheduled()` and `jobUnscheduled()` Methods

The Scheduler calls these methods when a new JobDetail is scheduled or unscheduled, respectively.

The `TRiggerFinalized()` Method

The Scheduler calls this method when a trigger has reached the state that it will never fire again. Unless the job has been set up as durable, it will be removed from the Scheduler.

The `triggersPaused()` Method

The Scheduler calls this method when a trigger or group of triggers has been paused . If it's a trigger group, the triggerName parameter will be null.

The `triggersResumed()` Method

The Scheduler calls this method when a trigger or group of triggers has been unpaused (or resumed). If it's a trigger group, the triggerName parameter will be null.

The `jobsPaused()` Method

The Scheduler calls this method when a JobDetail or a group of JobDetails has been paused.

The `jobsResumed()` Method

The Scheduler calls this method when a job or a group of jobs has been unpaused (or resumed). If it's a job group, the jobName parameter will be null.

The `schedulerError()` Method

The Scheduler calls this method when a serious error has occurred during the normal runtime of the Scheduler. The type of error can vary, but a few examples are listed here:

Problems instantiating a job class
Problems trying to find the next trigger
Repeated problems with the JobStore
DataStore connection problems

You can use the getErrorCode() or getUnderlyingException() methods of the SchedulerException to get more information about the specific error.

The schedulerShutdown() Method

The Scheduler calls this method to inform the SchedulerListener that the Scheduler is shutting down.

Listing 7.10 shows a simple SchedulerListener implementation.

Listing 7.10. A Simplified `SchedulerListener` Implementation

package org.cavaness.quartzbook.chapter7;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.quartz.SchedulerException;
import org.quartz.SchedulerListener;
import org.quartz.Trigger;

public class SimpleSchedulerListener implements SchedulerListener {
     Log logger = LogFactory.getLog(SimpleSchedulerListener.class);

     public void jobScheduled(Trigger trigger) {
          String jobName = trigger.getJobName();
          logger.info(jobName + " has been scheduled");
     }

     public void jobUnscheduled(String triggerName,
          String triggerGroup) {

          if (triggerName == null) {
               // triggerGroup is being unscheduled
               logger.info(triggerGroup + " is being unscheduled");
          } else {
               logger.info(triggerName + " is being unscheduled");
          }
     }

     public void triggerFinalized(Trigger trigger) {
          String jobName = trigger.getJobName();
          logger.info("Trigger is finished for " + jobName);
     }

     public void triggersPaused(String triggerName,
          String triggerGroup) {

          if (triggerName == null) {
               // triggerGroup is being unscheduled
               logger.info(triggerGroup + " is being paused");
          } else {
              logger.info(triggerName + " is being paused");
          }
     }

     public void triggersResumed(String triggerName,
          String triggerGroup) {

          if (triggerName == null) {
              // triggerGroup is being unscheduled
              logger.info(triggerGroup + " is now resuming");
          } else {
              logger.info(triggerName + " is now resuming");
          }
    }

    public void jobsPaused(String jobName, String jobGroup) {
         if (jobName == null) {
              // triggerGroup is being unscheduled
              logger.info(jobGroup + " is pausing");
         } else {
              logger.info(jobName + " is pausing");
         }
    }

    public void jobsResumed(String jobName, String jobGroup) {
         if (jobName == null) {
              // triggerGroup is being unscheduled
              logger.info(jobGroup + " is now resuming");
         } else {
              logger.info(jobName + " is now resuming");
         }
    }

    public void schedulerError(String msg, SchedulerException cause) {
         logger.error(msg, cause.getUnderlyingException());
    }

    public void schedulerShutdown() {
         logger.info("Scheduler is being shutdown");
    }
}

As with the previous examples, the SimpleSchedulerListener in Listing 7.10 provides simple implementations for the listener methods. Listing 7.11 uses the SimpleSchedulerListener class.

Listing 7.11. Using the `SimpleSchedulerListener`

package org.cavaness.quartzbook.chapter7;

import java.util.Date;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.cavaness.quartzbook.common.PrintInfoJob;
import org.quartz.JobDetail;
import org.quartz.Scheduler;
import org.quartz.SchedulerException;
import org.quartz.SchedulerListener;
import org.quartz.Trigger;
import org.quartz.TriggerUtils;
import org.quartz.impl.StdSchedulerFactory;

public class Listing_7_11 {
     static Log logger = LogFactory.getLog(Listing_7_11.class);

     public static void main(String[] args) {
          Listing_7_11 example = new Listing_7_11();
          try {
               example.startScheduler();
          } catch (SchedulerException ex) {
               logger.error(ex);
          }
     }

     public void startScheduler() throws SchedulerException {

         // Create an instance of the factory
         Scheduler scheduler = null;

         // Create the scheduler and JobDetail
         scheduler = StdSchedulerFactory.getDefaultScheduler();

         // Create and register the scheduler listener
         SchedulerListener schedulerListener =
              new SimpleSchedulerListener();

         scheduler.addSchedulerListener(schedulerListener);

         // Start the scheduler
         scheduler.start();
         logger.info("Scheduler was started at " + new Date());

         // Create the JobDetail
         JobDetail jobDetail = new JobDetail("PrintInfoJob",
                   Scheduler.DEFAULT_GROUP, PrintInfoJob.class);

         /*
          * Set up a trigger to start firing now, with no end
          * date/time, repeat forever and have 5 secs
          * between each firing.
          */
         Trigger trigger = TriggerUtils.makeSecondlyTrigger(5);
         trigger.setName("SimpleTrigger");
         trigger.setStartTime(new Date());

         // Register the JobDetail and Trigger
         scheduler.scheduleJob(jobDetail, trigger);
     }
}

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

We changed some things in Listing 7.11 from the previous examples, to actually cause more of the SchedulerListener methods to be called. In Listing 7.11, the Scheduler is created and started before the job is registered. This is so the jobScheduled() method gets called when the job is scheduled. We also changed the trigger to repeat two times instead of running indefinitely. This forces the triggerFinalized() method to be called because there were no more firing times for the trigger. Other than these contrived conditions, using the SchedulerListener is the same as using the job or trigger listeners.