org.osesb.scheduledjobs
Class ScheduledJob

java.lang.Object
  org.osesb.scheduledjobs.ScheduledJob

All Implemented Interfaces:

java.lang.Runnable, org.quartz.Job, org.quartz.StatefulJob

Direct Known Subclasses:

DefaultDatabasePollerScheduledJob

public abstract class ScheduledJob
extends java.lang.Object
implements org.quartz.StatefulJob, java.lang.Runnable

Abstract ancestor for scheduled jobs.

ScheduledJob(s) can be configured as Quartz-based Jobs or as Runnable(s).

ScheduledJob(s) implement the org.quartz.StatefulJob and Runnable interfaces. ScheduledJob(s) include a method named executeJob(), which descendents override to do real work.

When configured as a Quartz Job, org.quartz.Job#execute() invokes executeJob(). When configured as a Runnable job, run() invokes executeJob().

Generally, ScheduledJob(s) are used by the framework to poll external systems for data and send messages to an osESB transport handler for processing. ScheduledJob(s) are therefore useful in situations where an external system cannot send messages to osESB directly, but instead, generates events for processing by osESB.

Out of the box, there are ScheduledJob classes that poll databases, JMS Destinations, and file systems for changes and send messages to an osESB transport handler for processing. Current ScheduledJob classes include:

• Database poller scheduled jobs, which monitor one or more database tables for changes and send messages to an osESB transport handler for processing. See the org.osesb.scheduledjobs.databasepoller package.
• Directory poller scheduled jobs, which monitor the file system for changes and send messages to an osESB transport handler for processing. See the org.osesb.scheduledjobs.directorypoller package.
• JMS Destination poller scheduled jobs, which monitor JMS Destinations for mew messages and send messages to an osESB transport handler for processing. See the org.osesb.scheduledjobs.jmspoller package.

A ScheduledJobManager loads and starts ScheduledJobs that are configured by ScheduledJobConfiguration(s). ScheduledJobConfiguration extends XMLConfiguration to include the following properties:

• <displayStartupMessageFlag>, which determines if a startup message is logged when ScheduledJobManager starts a ScheduledJob
• <heartbeatInterval>, if set, a heartbeat message is logged every heartbeatInterval seconds. The heartbeat message is a health check for the ScheduledJob and the heartbeatInterval is independent of the job repeat interval or cron specification. The schedule configuration is used by ScheduledJobManager to configure and start a ScheduledJob.
• <schedule-configuration>, which includes the repeat interval for periodic jobs OR a cron expression for Quartz-based cron jobs. Periodic jobs start executing when the first interval after the job start time expires and then repeat indefinitely. Cron jobs are executed according to the configured cron expression.
• <job-configuration>, which contains the application-specific properties that are required to execute the job. The <job-config-class> element determines the class that is loaded for the job configuration. The job configuration class defaults to XMLConfiguration.

ScheduledJobManager(s) do not depend on a J2EE application server and can be deployed anywhere, but are typically deployed on the same platform that hosts the J2EE app server that runs osESB.

ScheduledJob(s) can communicate with osESB transport handlers using a org.osesb.msgrouting.configuration.ClientGateway. Typically, the ClientGateway configures a org.osesb.messagepipeline.MessagePipeline with org.osesb.messagepipeline.PipelineStage(s) that:

• Create a message formatted for osESB processing. Generally, this is a XML message, possibly with attachments.
• Send the message to an osESB transport handler using SOAP or JMS.

Since:

Version .9

Field Summary

static java.lang.String	JOBDATA_MAP_KEY_JOBNAME Job property key for the name of the Job.
static java.lang.String	JOBDATA_MAP_KEY_JOBSTARTEDTIMESTAMP Job property key for the java.util.Date the Job was started.
static java.lang.String	JOBDATA_MAP_KEY_JOBTYPE Job property key for the Job type, which is either 'quartz' or 'runnable'.
static java.lang.String	JOBDATA_MAP_KEY_LASTHEARTBEATTIMESTAMP Job property key for the java.util.Date for the last time a heartbeat message was logged.
static java.lang.String	JOBDATA_MAP_KEY_LASTJOBTIMESTAMP Job property key for the java.util.Date for the last time job was run.
static java.lang.String	JOBDATA_MAP_KEY_NUMBEROFTIMESEXECUTEJOB Job property key for the Integer number of times the job was run.
protected org.quartz.JobExecutionContext	jobExecutionContext ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
protected java.util.Map	jobPropertyMap A Map of job properties, which is used to maintain job statistics.
protected java.lang.Thread	jobThread ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
protected boolean	jobThreadStopping ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
protected java.lang.String	jobType ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
protected static org.apache.commons.logging.Log	log The logging implementation for this class.
static java.lang.String	QUARTZ_JOB_TYPE ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
static java.lang.String	RUNNABLE_JOB_TYPE ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).
protected ScheduledJobConfiguration	scheduledJobConfiguration The ScheduledJobConfiguration for this ScheduledJob.
protected java.lang.String	thisClassName The full name of this class.

Constructor Summary

ScheduledJob()
Creates a new, uninitalized instance of ScheduledJob.

ScheduledJob(ScheduledJobConfiguration scheduledJobConfiguration)
Creates a new, uninitalized instance of ScheduledJob.

Method Summary

void	execute(org.quartz.JobExecutionContext context) org.quartz.Job interface.
void	executeJob() Execute the ScheduledJob according to the ScheduledJobConfiguration.
java.util.Map	getJobPropertyMap() Return a Map of job properties, which is used to maintain job statistics.
java.lang.String	getJobType() Return the jobType for this ScheduledJob.
ScheduledJobConfiguration	getScheduledJobConfiguration() Returns the ScheduledJobConfiguration for this ScheduledJob.
void	incrementJobStatistics() Increment job statistics.
void	joinJobThread() Wait indefinitely for jobThread to die.
void	joinJobThread(long millis) Waits at most millis milliseconds for jobThread thread to die.
boolean	logHeartbeatMessage() Log the heartbeat message if configured by the <heartbeatInterval> property in the ScheduledJobConfiguration.
static java.lang.String	logMessage(java.lang.String messageText, ScheduledJob scheduledJob) Constructs and returns a message for Exceptions and logs.
void	run() Run the ScheduledJob thread.
void	start() Start a Runnable ScheduledJob.
void	stop() Stop a Runnable ScheduledJob.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static org.apache.commons.logging.Log log

The logging implementation for this class.

thisClassName

protected java.lang.String thisClassName

The full name of this class.

scheduledJobConfiguration

protected ScheduledJobConfiguration scheduledJobConfiguration

The ScheduledJobConfiguration for this ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz ScheduledJob(s), scheduledJobConfiguration is set by execute(). For Runnable ScheduledJob(s), scheduledJobConfiguration is set by the constructor that takes a ScheduledJobConfiguration as the parameter.

For Quartz-based ScheduledJobs, ScheduledJob#execute() expects a ScheduledJobConfiguration to be passed as an entry in the org.quartz.JobDataMap using ScheduledJobManager.JOBDATA_MAP_KEY_SCHEDULEDJOBCONFIGURATION as the key.

A ScheduledJobConfiguration extends XMLConfiguration to include the following properties:

1. <displayStartupMessageFlag>, which determines if a startup message is logged when ScheduledJobManager starts a ScheduledJob
2. <heartbeatInterval>, if set, a heartbeat message is logged every heartbeatInterval seconds.
3. <schedule-configuration>, which includes the repeat interval for periodic jobs OR a cron expression for Quartz-based cron jobs. Periodic jobs start executing when the first interval after the job start time expires and then repeat indefinitely. Cron jobs are executed according to the configured cron expression. The schedule configuration is used by ScheduledJobManager to configure and start a ScheduledJob.
4. <job-configuration>, which contains the application-specific properties that are required to execute the job. The <job-config-class> element determines the class that is loaded for the job configuration. The job configuration class defaults to XMLConfiguration.

jobExecutionContext

protected org.quartz.JobExecutionContext jobExecutionContext

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, this is the JobExecutionContext.

See Also:

start(), stop(), run()

jobThread

protected java.lang.Thread jobThread

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). jobThread is the Thread for Runnable ScheduledJob(s).

See Also:

start(), stop(), run()

jobThreadStopping

protected boolean jobThreadStopping

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). jobThreadStopping is the jobThread run() flag for Runnable ScheduledJob(s).

See Also:

start(), stop(), run()

jobPropertyMap

protected java.util.Map jobPropertyMap

A Map of job properties, which is used to maintain job statistics.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, job statistics are maintaiuned in the org.quartz.JobDataMap and jobPropertyMap is populated by execute(). For Runnable jobs, job statistics are maintaiuned in jobPropertyMap.

Job statistics include:

• A timestamp for when the job was started.
• The number of times the job has run.
• A timestamp for the last time the job was run.
• Statistics that are specific to the descendant of ScheduledJob.

See Also:

incrementJobStatistics(), logHeartbeatMessage()

jobType

protected java.lang.String jobType

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, jobType is QUARTZ_JOB_TYPE. For Runnable jobs, jobType is RUNNABLE_JOB_TYPE.

jobType defaults to QUARTZ_JOB_TYPE and is set to RUNNABLE_JOB_TYPE by the constructor that takes a ScheduledJobConfiguration as the argument.

See Also:

getJobType()

QUARTZ_JOB_TYPE

public static java.lang.String QUARTZ_JOB_TYPE

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, jobType is QUARTZ_JOB_TYPE. For Runnable jobs, jobType is RUNNABLE_JOB_TYPE.

jobType defaults to QUARTZ_JOB_TYPE and is set to RUNNABLE_JOB_TYPE by the constructor that takes a ScheduledJobConfiguration as the argument.

See Also:

getJobType()

RUNNABLE_JOB_TYPE

public static java.lang.String RUNNABLE_JOB_TYPE

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, jobType is QUARTZ_JOB_TYPE. For Runnable jobs, jobType is RUNNABLE_JOB_TYPE.

jobType defaults to QUARTZ_JOB_TYPE and is set to RUNNABLE_JOB_TYPE by the constructor that takes a ScheduledJobConfiguration as the argument.

See Also:

getJobType()

JOBDATA_MAP_KEY_JOBNAME

public static final java.lang.String JOBDATA_MAP_KEY_JOBNAME

Job property key for the name of the Job.

See Also:

Constant Field Values

JOBDATA_MAP_KEY_JOBTYPE

public static final java.lang.String JOBDATA_MAP_KEY_JOBTYPE

Job property key for the Job type, which is either 'quartz' or 'runnable'.

See Also:

Constant Field Values

JOBDATA_MAP_KEY_JOBSTARTEDTIMESTAMP

public static final java.lang.String JOBDATA_MAP_KEY_JOBSTARTEDTIMESTAMP

Job property key for the java.util.Date the Job was started.

See Also:

Constant Field Values

JOBDATA_MAP_KEY_NUMBEROFTIMESEXECUTEJOB

public static final java.lang.String JOBDATA_MAP_KEY_NUMBEROFTIMESEXECUTEJOB

Job property key for the Integer number of times the job was run.

See Also:

Constant Field Values

JOBDATA_MAP_KEY_LASTJOBTIMESTAMP

public static final java.lang.String JOBDATA_MAP_KEY_LASTJOBTIMESTAMP

Job property key for the java.util.Date for the last time job was run.

See Also:

Constant Field Values

JOBDATA_MAP_KEY_LASTHEARTBEATTIMESTAMP

public static final java.lang.String JOBDATA_MAP_KEY_LASTHEARTBEATTIMESTAMP

Job property key for the java.util.Date for the last time a heartbeat message was logged.

See Also:

Constant Field Values

Constructor Detail

ScheduledJob

public ScheduledJob()

Creates a new, uninitalized instance of ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). This is the no-argument constructor used by the Quartz scheduler.

ScheduledJob

public ScheduledJob(ScheduledJobConfiguration scheduledJobConfiguration)
             throws java.lang.Exception

Creates a new, uninitalized instance of ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). This is the constructor used to construct the Runnable ScheduledJob.

Parameters:

scheduledJobConfiguration - The ScheduledJobConfiguration for this ScheduledJob.

Throws:

java.lang.Exception - if constructed with a null scheduledJobConfiguration.

Method Detail

execute

public void execute(org.quartz.JobExecutionContext context)
             throws org.quartz.JobExecutionException

org.quartz.Job interface.

Invoked by the Scheduler when a Trigger fires that is associated with the Job.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). Generally org.quartz.Job#execute() invokes executeJob(), which descendents override to do real work.

The execute() method of this ancestor class expects a ScheduledJobConfiguration to be passed as an entry in the org.quartz.JobDataMap using ScheduledJobManager.JOBDATA_MAP_KEY_SCHEDULEDJOBCONFIGURATION as the key. Execute() retrieves the ScheduleJobConfigurationfrom the Quartz JobDataMap and sets this.scheduledJobConfiguration.

The ancestor method also copies job properties and statistics in JobDataMap to jobPropertyMap and logs a heartbeat message if the 'heartbeatIntervalSeconds' propery in ScheduledJobConfiguration is > 0.

Specified by:

execute in interface org.quartz.Job

Parameters:

context - The Quartz JobExecutionContext.

Throws:

org.quartz.JobExecutionException - if a ScheduledJobConfiguration cannot be retrieved from the Quartz JobDataMap.

See Also:

Job.execute(org.quartz.JobExecutionContext)

run

public void run()

Run the ScheduledJob thread.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).

This is the run() method for a Runnable ScheduledJob.

When configured as a Quartz Job, org.quartz.Job#execute() invokes executeJob(). When configured as a Runnable job, run() invokes executeJob().

Specified by:

run in interface java.lang.Runnable

See Also:

start(), stop()

executeJob

public void executeJob()
                throws java.lang.Exception

Execute the ScheduledJob according to the ScheduledJobConfiguration.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). When configured as a Quartz Job, org.quartz.Job#execute() invokes executeJob(). When configured as a Runnable job, run() invokes executeJob().

This ancestor method logs that executeJob() was invoked.

Throws:

java.lang.Exception - org.quartz.JobExecutionException if there is a problem completing the executeJob() method.

start

public void start()

Start a Runnable ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s).

When configured as a Runnable job, ScheduledJobManager will invoke start() to create and start jobThread and set dateTimeJobStarted. When configured as a Quartz job, ScheduledJobManager will invoke org.quartz.Scheduler#start() to start the job.

stop

public void stop()

Stop a Runnable ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). When configured as a Runnable job, invoke stop() to end jobThread.

joinJobThread

public void joinJobThread()

Wait indefinitely for jobThread to die.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). jobThread is the Thread for Runnable ScheduledJob(s).

joinJobThread

public void joinJobThread(long millis)

Waits at most millis milliseconds for jobThread thread to die.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). jobThread is the Thread for Runnable ScheduledJob(s).

incrementJobStatistics

public void incrementJobStatistics()

Increment job statistics.

See Also:

logHeartbeatMessage()

logHeartbeatMessage

public boolean logHeartbeatMessage()

Log the heartbeat message if configured by the <heartbeatInterval> property in the ScheduledJobConfiguration.

Returns:

true if the heartbeat message was logged, false otherwise. A heartbeat message is logged if the <heartbeatInterval> is configured and if the configured <heartbeatInterval> has elapsed.

getScheduledJobConfiguration

public ScheduledJobConfiguration getScheduledJobConfiguration()

Returns the ScheduledJobConfiguration for this ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz ScheduledJob(s), scheduledJobConfiguration is set by execute(). For Runnable ScheduledJob(s), scheduledJobConfiguration is set by the constructor that takes a ScheduledJobConfiguration as the parameter.

For Quartz-based ScheduledJobs, ScheduledJob#execute() expects a ScheduledJobConfiguration to be passed as an entry in the org.quartz.JobDataMap using ScheduledJobManager.JOBDATA_MAP_KEY_SCHEDULEDJOBCONFIGURATION as the key.

A ScheduledJobConfiguration extends XMLConfiguration to include the following properties:

1. <displayStartupMessageFlag>, which determines if a startup message is logged when ScheduledJobManager starts a ScheduledJob
2. <heartbeatInterval>, if set, a heartbeat message is logged every heartbeatInterval seconds.
3. <schedule-configuration>, which includes the repeat interval for periodic jobs OR a cron expression for Quartz-based cron jobs. Periodic jobs start executing when the first interval after the job start time expires and then repeat indefinitely. Cron jobs are executed according to the configured cron expression. The schedule configuration is used by ScheduledJobManager to configure and start a ScheduledJob.
4. <job-configuration>, which contains the application-specific properties that are required to execute the job. The <job-config-class> element determines the class that is loaded for the job configuration. The job configuration class defaults to XMLConfiguration.

Returns:

the ScheduledJobConfiguration for this ScheduledJob.

getJobPropertyMap

public java.util.Map getJobPropertyMap()

Return a Map of job properties, which is used to maintain job statistics.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, job statistics are maintaiuned in the org.quartz.JobDataMap and jobPropertyMap is populated by execute(). For Runnable jobs, job statistics are maintaiuned in jobPropertyMap.

Job statistics include:

• A timestamp for when the job was started.
• The number of times the job has run.
• A timestamp for the last time the job was run.
• Statistics that are specific to the descendant of ScheduledJob.

Returns:

a Map of job properties, which is used to maintain job statistics.

See Also:

incrementJobStatistics(), logHeartbeatMessage()

getJobType

public java.lang.String getJobType()

Return the jobType for this ScheduledJob.

ScheduledJob(s) can be configured as Quartz Jobs or as Runnable(s). For Quartz Jobs, jobType is QUARTZ_JOB_TYPE. For Runnable jobs, jobType is RUNNABLE_JOB_TYPE.

jobType defaults to QUARTZ_JOB_TYPE and is set to RUNNABLE_JOB_TYPE by the constructor that takes a ScheduledJobConfiguration as the argument.

Returns:

the jobType for this ScheduledJob.

logMessage

public static java.lang.String logMessage(java.lang.String messageText,
                                          ScheduledJob scheduledJob)

Constructs and returns a message for Exceptions and logs.

Appends the following information to the message text and returns an augmented String.

• The name of the ScheduledJob.
• The path for the ScheduledJobConfiguration file.

Parameters:

messageText - The basic message text.

scheduledJob - The ScheduledJob that will log the message.

Returns:

the augmented message text.