Using JobStoreTX

The first persistent JobStore that we discuss is called JobStoreTX. The "TX" in the name stands for "transaction." As we stated earlier, the JobStoreTX is designed to be used in an environment in which you want Quartz to manage the transactions. For example, if you are building a J2SE application and are not using an application server such as WebLogic or JBoss, JobStoreTX would be the right choice for a persistent JobStore.

In the last section, you saw how easy it is to configure the RAMJobStore. We mentioned that one of the advantages to the RAMJobStore is its simple configuration. We've already discussed what has to be done to the database to get it ready; we now discuss what's needed to configure the Quartz application for a JDBC JobStore.

Configuring the JobStoreTX

To tell the Quartz runtime environment that you want to use a JobStore other than the default RAMJobStore, you must configure several properties. It doesn't matter what order you do them in, but they all must be done before you run the application for the first time.

Setting the JobStore Property

To inform the Scheduler that JobStoreTX should be used, you must add the following line to the quartz.properties file:

org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX

Be sure to remove the RAMJobStore line (if present) when switching to the JobStoreTX.

Configuring the Driver Delegate

In the same way that the JDBC API relies on a JDBC driver designed specifically for a database platform, Quartz relies on a DriverDelegate to communicate with a given database. As the name implies, database calls from the Scheduler to the JobStore are delegated to a preconfigured DriverDelegate instance. The delegate is responsible for all communications with the JDBC driver and, thus, the database.

All DriverDelegate classes extend the org.quartz.impl.jdbcjobstore.StdDriverDelegate class. The StdDriverDelegate has base functionality that all delegates, regardless of platform, can use. However, there is enough difference between some of these database platforms that a specialized delegate needs to be created for some platforms. Table 6.2 lists the specialized delegates.

Table 6.2. You Must Configure One of the DriverDelegates Classes for Your Platform

Database Platform	Quartz Delegate Class
Cloudscape/Derby	org.quartz.impl.jdbcjobstore.CloudscapeDelegate
DB2 (version 6.x)	org.quartz.impl.jdbcjobstore.DB2v6Delegate
DB2 (version 7.x)	org.quartz.impl.jdbcjobstore.DB2v7Delegate
DB2 (version 8.x)	org.quartz.impl.jdbcjobstore.DB2v8Delegate
HSQLDB	org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
MS SQL Server	org.quartz.impl.jdbcjobstore.MSSQLDelegate
Pointbase	org.quartz.impl.jdbcjobstore.PointbaseDelegate
PostgreSQL	org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
(WebLogic JDBC Driver)	org.quartz.impl.jdbcjobstore.WebLogicDelegate
(WebLogic 8.1 with Oracle)	org.quartz.impl.jdbcjobstore.oracle.weblogic.WebLogicOracleDelegate
Oracle	org.quartz.impl.jdbcjobstore.oracle.OracleDelegate

What If My Database Platform Is Not Listed in Table 6 2?

If your RDBMS isn't listed here, there is a good chance it will work with the standard JDBC delegate, org.quartz.impl.jdbcjobstore.StdDriverDelegate.

After you determine which delegate you need based on your database platform, you need to add the following to the quartz.properties file:

org.quartz.jobStore.driverDelegateClass=

As an example, if you are using MS SQL Server as your database platform, you would need to add the following to the properties file:

org.quartz.jobStore.driverDelegateClass=
 org.quartz.impl.jdbcjobstore.MSSQLDelegate

 

Configuring the Database Table Prefix

Back when we first discussed the database tables for Quartz, we mentioned that all the tables had the prefix QRTZ_ added to them. Under certain circumstances, you might need to create multiple sets of Quartz database tables. In that situation, you would need to change the prefix for each set.

The prefixes for the table names are configured in the quartz.properties file using the property org.quartz.jobStore.tablePrefix. To change the prefix, just set the property to a different value:

org.quartz.jobStore.tablePrefix = SCHEDULER2_

Make sure the table names all start with this prefix.

Database Table and Column Names

Just in case you were wondering, the names for the database tables (minus the prefixes) and the table column names are in the org.quartz.impl.jdbcjobstore.Constants interface. This interface is implemented by the JobStoreSupport class, and the constant values are used within the JobStoreTX or JobStoreCMT classes.

Table 6.3 shows the set of properties that can be used to tune the JobStoreTX.

Table 6.3. The Configuration Properties Available to Be Set for JobStoreTX

Property	Default
org.quartz.jobStore.driverDelegateClass
Description: Driver delegates understand the particular dialects of various database systems.
org.quartz.jobStore.dataSource
Description: This is the name used in the DataSource configuration section of the quartz.properties file.
org.quartz.jobStore.tablePrefix	QRTZ_
Description: This is the prefix given to the set of database tables for this Scheduler. Schedulers can use different tables from the same database if the prefixes are different.
org.quartz.jobStore.useProperties	False
Description: The "use properties" flag instructs the persistent JobStore that all values in JobDataMaps will be Strings and, therefore, can be stored as name-value pairs instead of storing more complex objects in their serialized form in the BLOB column. This is can be handy because you avoid the class-versioning issues that can arise from serializing your non-String classes into a BLOB.
org.quartz.jobStore.misfireThreshold	60000
Description: The number of milliseconds the Scheduler will tolerate a trigger to pass its next-fire-time before being considered misfired. The default value (if you don't make an entry of this property in your configuration) is 60000 (60 seconds). This is not specific to JDBC-JobStore; it is also a parameter used by RAMJobStore.
org.quartz.jobStore.isClustered	False
Description: Set this to true to turn on clustering features. This property must be set to true if you are having multiple instances of Quartz use the same set of database tables.
org.quartz.jobStore.clusterCheckinInterval	15000
Description: Set the frequency (in milliseconds) at which this instance checks in with the other instances of the cluster. This affects the quickness of detecting failed instances. It is used only when isClustered is set to true.
org.quartz.jobStore.maxMisfiresToHandleAtATime	20
Description: This is the maximum number of misfired triggers the JobStore will handle in a given pass. Handling many (more than a couple dozen) at once can cause the database tables to be locked long enough to hamper the performance of firing other (not yet misfired) triggers.
org.quartz.jobStore.dontSetAutoCommitFalse	False
Description: Setting this parameter to true tells Quartz not to call setAutoCommit(false) on connections obtained from the DataSource(s). This can be helpful in a few situations, such as if you have a driver that complains if it is called when it is already off. This property defaults to false because most drivers require that setAutoCommit(false) be called.
org.quartz.jobStore.selectWithLockSQL	SELECT * FROM {0}LOCKS WHERE LOCK_NAME = ? FOR UPDATE
Description: This must be a SQL string that selects a row in the LOCKS table and places a lock on the row. If it is not set, the default is SELECT * FROM {0}LOCKS WHERE LOCK_NAME = ? FOR UPDATE, which works for most databases. The {0} is replaced during runtime with the TABLE_PREFIX that you configured earlier.
org.quartz.jobStore.txIsolationLevelSerializable	False
Description: A value of true tells Quartz (when using JobStoreTX or CMT) to call setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE) on JDBC connections. This can be helpful to prevent lock timeouts with some databases under high load and long-lasting transactions.