Quartz Utility Plug-Ins

The Quartz framework includes several plug-ins that you can use in your application. This section briefly describes them and their purpose.

JobInitializationPlugin

We've already talked several times about this plug-in. It loads job and trigger information from an XML file (by default, quartz_jobs.xml). You can configure the name of the file by setting the filename parameter in the quartz.properties file for the plug-in. If you don't require a database to store your jobs or if you need the capability to quickly test specific jobs, this plug-in is very helpful.

JobInitializationPluginMulitple

The JobInitializationPluginMultiple is similar to the JobInitializationPlugin, as evident by its similar name. The difference is that it supports loading from multiple XML files instead of just one. In some ways, it's similar to the JobLoaderPlugin in Listing 8.2, except that the plug-in in Listing 8.2 looks at a directory instead of a set of files.

The files for the JobInitializationPluginMultiple are comma separated and specified in the quartz.properties file. A nice feature for this plug-in is that it can periodically scan the files for changes and then reload the job information when they change. It adds this behavior by implementing the org.quartz.jobs.FileScanListener. The scan interval (defined in seconds) can be specified in the properties file.

LoggingJobHistoryPlugin

The org.quartz.plugins.history.LoggingJobHistoryPlugin is used to log job history via the commons-logging framework. This includes job executions as well as any job vetoes. The plug-in allows for the log messages to be configurable but provides a default message format. The format can specify which fields from the job are included in the message. You can provide separate message formats for the following events:

• jobFailedMessage Logged when a job fails execution
• jobSuccessMessage Logged when a job completes execution
• jobToBeFiredMessage Logged when a job is about to be executed
• jobWasVetoedMessage Logged when a job gets vetoed

For example, if you wanted to override the default message for when a job is about to be executed and all you cared to see in the log message was the job name and time of execution, you could add this to the quartz.properties file:

[View full width]

org.quartz.plugin.jobHistory.class=org.quartz.plugins. history.LoggingJobHistoryPlugin org.quartz.plugin.jobHistory.jobToBeFiredMessage=Job {0} is about to be fired at: {2, date , HH:mm:ss MM/dd/yyyy}

You can include several data elements about the job in the log message. Table 8.1 lists the elements and their data types.

Table 8.1. The Elements That Can Be Used in the Job Message Format

Element #	Data Type	Description
0	String	The name of the job
1	String	The name of the group for the job
2	Date	The current date
3	String	The name of the trigger
4	String	The name of the group for the trigger
5	Date	The scheduled firing time
6	Date	The next Scheduler firing time
7	Integer	The refire count from the JobExecutionContext

Each event can be separately configured in the quartz.properties file. The only downside to using this plug-in is that if you have many jobs, the log files can fill up quite fast, and it almost becomes too much information.

LoggingTriggerHistoryPlugin

This plug-in is equivalent to the job history plug-in but is used for trigger history information instead. You can provide log message formats for the following trigger events:

• triggerCompleteMessage Logged when the trigger has finished all firings and will not fire again
• TRiggerFiredMessage Logged when a trigger fires
• triggerMisfiredMessage Logged after a trigger misfires

As with the LoggingJobHistoryPlugin, you can override the default message format in the properties file.

You can include several data elements about the job in the log message. Table 8.1 lists the elements and their data types. Table 8.2 lists the elements that can be used in the trigger history log message.

Table 8.2. The Elements that Can Be Used in the Trigger Message Format

Element #	Data Type	Description
0	String	The name of the trigger
1	String	The name of the group for the trigger
2	Date	The scheduled firing time
3	Date	The next firing time for the trigger
4	Date	The actual firing time of the trigger
5	String	The name of the job
6	String	The name of the group for the job
7	Integer	The refire count from the JobExecutionContext

Like the LoggingJobHistoryPlugin, this plug-in can log a lot of messages, especially if you have several triggers firing often.

ShutdownHookPlugin

This plug-in catches the shutdown event of the JVM and forces the Scheduler to shut down. You might be saying, "Why do I need to tell the Scheduler to shut down if the JVM is already shutting down?" The reason is mainly so the Scheduler can perform a "clean" shutdown.

When the initialize() method is called on the plug-in, it adds a new java.lang.Thread to the JVM. When the JVM gets a shutdown event, it is caused by one of two events:

• The program exits normally when the last nondaemon thread exits or when the System.exit() method is invoked.
• The JVM is terminated in response to user input, such as the user pressing Ctrl+C, or a system-wide event, such as a user logoff or system shutdown.

When the JVM gets the shutdown notification, it performs a callback to the shutdown thread and gives the thread a chance to run. In the case of the ShutdownHookPlugin, the run() method calls the Scheduler and tells it to shut down. Be default, the shutdown() call to the Scheduler includes a Boolean value of true, which tells the Scheduler to perform a "clean" shutdown. This means that the Scheduler will wait for all executing triggers before stopping.

You can tell the plug-in to not perform a clean shutdown by including that as a plug-in parameter in the quartz.properties file.