Chapter 7. Implementing Quartz Listeners

Listeners provide a convenient and unobtrusive mechanism for getting notified when certain events of interest occur. Quartz provides three types of listeners: one for jobs, one for triggers, and one for the Scheduler itself. This chapter explains how to use each type to better manage your Quartz applications and be aware of what events are occurring.

Listeners as Extension Points

The phrase extension point is used in software development to indicate a place in a framework or application where the creators expect users to extend or customize the framework to meet their needs. (You will also hear the word hook used for the same meaning.)

Quartz listeners are a type of extension point in which you, as a Quartz user , can extend the framework and customize it to do new things. This customization takes place within the listener class implementations that we show you how to build in this chapter.

Listeners are not the only extension points in the framework. Along with plug-ins and a few other customization options, listeners provide a simple means of customizing the framework and making it do what you need it to do. Because the extension points for listeners are supported through a publicized interface, you don't have to worry about creating your own branch of the code that then is unsupportable.

Implementing a Listener

In the discussion that follows , the approach for implementing a listener is generally the same for all three types. The steps can be generalized into the following:

1.	Create a Java class that implements the listener interface.
2.	Implement all the methods of the listener interface with logic that is specific to your application.
3.	Register the listener.

Creating the Listener Class

The listener is a Java interface and must be implemented by a concrete class. The class doesn't have to be a specialized class created just for this purpose; it can be any Java class that you want to receive the callback methods on. In keeping with good program design, you should be careful to keep tight cohesion but loose coupling. Seriously consider which class you decide to implement the listener with; this is important from an overall design perspective.

Implementing the Listener Methods

Because listeners are ordinary Java interfaces, every method must be implemented in your listener implementation class. If there are any methods in the listener interface that you are not interested in, you are allowed to have an empty body for the method; however, you still must provide a valid method implementation of it. For example, the following code snippet shows an empty method body for one of the

SchedulerListener methods:

... rest of the SchedulerListener not shown

public void schedulerShutdown(){
  // Don't care about the shutdown event
}

Registering the Listener

To receive the callback methods, the Scheduler must be aware of the listener instance. Figure 7.1 illustrates the process of registering a listener with the Scheduler and receiving the callbacks.

Figure 7.1. Listeners are registered with and receive callbacks from the Scheduler.

Global vs. Nonglobal Listeners

The JobListener and triggerListener can be registered as either a global or nonglobal listener. A global listener is one that receives event notifications for all jobs/triggers. A nonglobal listener (or just a standard listener) receives event notifications for only those jobs or triggers that have registered listeners on them.

Whether you register your listener as a global or nonglobal listener depends on your specific application needs. We provide examples of both ways in the following sections. Another way to look at global and nonglobal listeners comes from the creator of the Quartz framework. James House describes global and nonglobal listeners this way:

Global listeners are active in the sense that they are eagerly seeking every possible event in order to perform their task upon it. Generally, the work done by global listeners [is] not specific to the particular job or trigger. Nonglobal listeners are generally passive in the sense that they do nothing until a trigger fires or job executes that has specifically named that listener. Hence, nonglobal listeners are more likely than global listeners to modify or add to the work performed by the jobsomewhat like a decorator of the well-known decorator design pattern.