To start-up Quartz you need to uncomment a section in the konakartadmin webapp's web.xml file (this is located in the konakartadmin/WEB-INF directory).

You need to uncomment this section so that the QuartzInitializerServlet starts up when KonaKart starts.

<!-- Quartz Scheduler 
<servlet>
    <servlet-name>QuartzInitializer</servlet-name>
    <servlet-class>org.quartz.ee.servlet.QuartzInitializerServlet</servlet-class>
    <init-param>
        <param-name>shutdown-on-unload</param-name>
        <param-value>true</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>
End of Quartz Scheduler -->
	               

The Quartz properties file should be placed on the konakartadmin classpath (the installer will place it in the konakartadmin/WEB-INF/classes directory).

The following is the default for KonaKart:

#============================================================================
# Configure Main Scheduler Properties  
#============================================================================

org.quartz.scheduler.instanceName = KonaKartScheduler
org.quartz.scheduler.instanceId = AUTO

#============================================================================
# Configure ThreadPool  
#============================================================================

org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount = 3
org.quartz.threadPool.threadPriority = 5

#============================================================================
# Configure JobStore  
#============================================================================

org.quartz.jobStore.misfireThreshold = 60000
org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore

#============================================================================
# Configure Plugins 
#============================================================================

org.quartz.plugin.triggHistory.class = org.quartz.plugins.history.LoggingJobHistoryPlugin

org.quartz.plugin.jobInitializer.class = org.quartz.plugins.xml.XMLSchedulingDataProcessorPlugin
org.quartz.plugin.jobInitializer.fileNames = konakart_jobs.xml
org.quartz.plugin.jobInitializer.failOnFileNotFound = true
org.quartz.plugin.jobInitializer.scanInterval = 60
org.quartz.plugin.jobInitializer.wrapInUserTransaction = false

# No longer used
#org.quartz.plugin.jobInitializer.overWriteExistingJobs = true
                  

A useful parameter that you may wish to modify is the fileNames parameter which, by default, is set to "konakart_jobs.xml". The "konakart_jobs.xml" file contains definitions of the example KonaKart jobs that can be run.

It is possible that you may wish to have additional job definition files like "konakart_jobs.xml" for defining batch schedules for other stores in a multi-store environment. Additional job definition files can be added to the filenames property.

The default job definition file is called "konakart_jobs.xml" and is placed in the konakartadmin/WEB-INF/classes directory.

The following is an extract from "konakart_jobs.xml" that defines a single job:

<job>
    <name>RemoveExpiredCustomers</name>
    <group>KonaKart Batch Jobs store1</group>
    <description>Removes expired Customers for privacy and performance</description>
    <job-class>com.konakartadmin.bl.ExecuteBatchEE</job-class>
    <durability>false</durability>
    <recover>false</recover>
    <job-data-map>
      <entry>
        <key>credentialsFile</key>
        <value>konakart_jobs.properties</value>
      </entry>
      <entry>
        <key>executionClass</key>
        <value>com.konakartadmin.bl.AdminCustomerBatchMgr</value>
      </entry>
      <entry>
        <key>executionMethod</key>
        <value>removeExpiredCustomersBatch</value>
      </entry>
      <entry>
        <key>param0</key>
        <value>removeExpiredCustomers</value>
      </entry>
      <entry>
        <key>param1</key>
        <value>true</value>
      </entry>
      <entry>
        <key>param2</key>
        <value>25</value>
      </entry>
      <entry>
        <key>param3</key>
        <value>0-1-2-3</value>
      </entry>
    </job-data-map>
</job>
                  

This particular batch job removes expired sessions from KonaKart. Note the following parameters:

Note that the storeId is appended to the Group Name. This is important when running in multi-store mode as only the jobs for the current store are shown in the Admin Console.

job-class = com.konakartadmin.bl.ExecuteBatchEE

The job-class defines the class that Quartz will execute when the job is run. The ExecuteBatchEE class is the Quartz > KonaKart bridge class that can be used to call KonaKart batch jobs from jobs defined in Quartz.

Another job-class that can be used here is the com.konakartadmin.bl.ExecuteMultiStoreBatchEE job class. This Quartz > KonaKart bridge class executes the specified job in a loop, once for every enabled store. Note that this job will use the credentials specified in the konakart_jobs.properies file to access each store in turn so these credentials need to be valid for each store. There are two special parameters available for these jobs used for including stores or excluding stores for execution. The parameters are called includedStores and excludedStores. You can find examples of their use in the default konakart_jobs.xml file. These parameters are useful for specifying exactly which stores you want the job to run for and which stores you do not want the batch jobs to run for.

key: credentialsFile = konakart_jobs.properties

Inside the job-data-map tag an entry is defined that contains the name of a KonaKart "Credentials" file. The file can be named anything you like but it must be located on the class path so that ExecuteBatchEE can access it. In our example, the file is called "konakart_jobs.properties" (see below for more detail on the contents of this file). The credentials are required so that the ExecuteBatchEE class can create and log into a KonaKart Admin Engine, then finally execute the "execute()" API call on that engine to run the defined batch job.

key: executionClass = com.konakartadmin.bl.AdminCustomerBatchMgr

The execution class is the name of the class that will be instantiated by KonaKart to execute the defined batch job. It is possible to define your own class as the executionClass which is an excellent way to extend KonaKart's batch functionality.

key: executionMethod = removeExpiredCustomersBatch

The execution method is the name of the method on the executionClass that will be executed by KonaKart to run the defined batch job. It is possible to define your own class and methods as described above to extend KonaKart functionality as you require.

key: param0, param1, ..., paramN

The "param" keys are the parameters that are passed to the batch job. These can be whatever the batch job needs but must be represented as strings and the ordering is significant.

It is essential that you name the parameters "param0", "param1" and so on for each of the parameters.

In our example, param0, the first argument, is used in this job to define the name of the log file produced by the batch job.

If you wish to pass the session Id of the logged-on user who will execute the job you can define a parameter with the special value SESSION_ID . If KonaKart sees a parameter with this value it will replace it with the session Id used to run the execute() API call which is used by the KonaKart batch architecture. Other than this runtime replacement the parameter is identical to the other parameters so needs to be defined on your method signature in the correct position. If in doubt check the examples under the batch directory of your installation which can be found under the custom directory at the top level of your KonaKart home directory. Full source code is provided (Business and Enterprise Editions Only) for the example batch jobs such as in *\KonaKart\custom\batch\src\com\konakartadmin\bl\AdminCustomerBatchMgr.java .

Quartz executes the defined jobs when defined "Triggers" fire. These triggers are also defined in the konakart_jobs.xml file:

The following is an extract from "konakart_jobs.xml" that defines a single trigger:

<trigger>
    <cron>
        <name>RemoveExpiredCustomersTrigger</name>
        <group>KonaKart Triggers</group>
        <description>Trigger for RemoveExpiredCustomers</description>
        <job-name>RemoveExpiredCustomers</job-name>
        <job-group>KonaKart Batch Jobs store1</job-group>
        <!-- every hour           0 0 * ? * *    -->
        <!-- every 30 seconds     0,30 * * ? * * -->
        <!-- every day @ 9:00pm   0 0 21 ? * *   -->
        <cron-expression>0 5 21 ? * *</cron-expression>       
    </cron>
</trigger>
                  

This is where you define when you want a particular batch job to be executed.

In this case we have chosen to use the cron trigger definition but Quartz provides other trigger mechanisms that you can easily use instead if you prefer.

Some examples of cron expressions are provided (commented out).

The default job definition credentials file is called "konakart_jobs.properties" and is placed in the konakartadmin/WEB-INF/classes directory.

The file name is actually defined in the "konakart_jobs.xml" file - see the credentialsFile tag above. Hence, you can easily change the name to suit your needs. You can also have more than one credentials file - which would be required if you needed to run batch jobs on different stores, in a multi-store configuration, where the access credentials needed to be different for the different jobs.

The following is an extract from "konakart_jobs.properties" that defines the parameters required to create and log in to an Admin Engine:

#============================================================================
# konakart_jobs.properties
#
# Used to define the credentials for batch jobs.
# If multiple configurations are required, use multiple files and define
# these in the credentials tag in konakart_jobs.xml.
#============================================================================

# ---------------------------------------------------------------------------
# Credentials to use for the batch jobs - use these when customers are shared
# or for Single Store: 

konakart.user     = admin@konakart.com
konakart.password = princess
                  

It is recommended that you secure this file appropriately as it could contain the credentials of a privileged Admin user.

Other configuration options are possible in credentials files (eg. the engine class can be defined and the properties files it uses can be defined). If the other configuration parameters are left commented out default values are used.

By default, Quartz is set up in KonaKart to run in a high-performance RAM store in just one webapp. It's possible to use a JDBC store and configure Quartz to operate in a load balanced and fault tolerant fashion. The set-up for this Clustered Quartz mode is described here.

You need to make modifications to the quartz.properties file in the konakartadmin webapp (WEB-INF/classes directory) as follows:

Uncomment the org.quartz.jobStore parameters and ensure you are using org.quartz.impl.jdbcjobstore.JobStoreTX as the org.quartz.jobStore.class rather than the default org.quartz.simpl.RAMJobStore.

Here is an example for PostgreSQL:

#============================================================================
# Configure JobStore  
# Default is the RAMJobStore which is simple and gives the best performance
# See User Guide for Set-Up of the JDBCJobStoreTX
#============================================================================

org.quartz.jobStore.misfireThreshold = 60000
#org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore

org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.isClustered = true
org.quartz.jobStore.clusterCheckinInterval = 1500
org.quartz.jobStore.maxMisfiresToHandleAtATime = 1

org.quartz.jobStore.dataSource = myDS

#============================================================================
# Configure DataSource
#============================================================================

org.quartz.dataSource.myDS.driver = org.postgresql.Driver
org.quartz.dataSource.myDS.URL = jdbc:postgresql://chelski:5432/chelski12
org.quartz.dataSource.myDS.user = chelski1
org.quartz.dataSource.myDS.password = myPassword
org.quartz.dataSource.myDS.maxConnections = 10
org.quartz.dataSource.myDS.validationQuery = SELECT 1

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

Ensure that the data source is correctly defined in the quartz.properties file . The tables Quartz needs to implement its clustering are populated with your batch job details at the start-up of Quartz.

A quartz_setup.sql script needs to be run to create the tables needed by Quartz to implement its clustering. We provide a script for each supported database (in a file called quartz_setup.sql in the database directory for each database). The provided script should work but if not refer to the Quartz website where various set-up scripts are contributed for this purpose. (There are different scripts for different versions of the databases).

It is possible that you may need an alternative org.quartz.jobStore.driverDelegateClass definition to the one specified by default for your database. Refer to the Quartz website where various alternative Delegate classes are explained for this purpose.