com.goldencode.p2j.scheduler

Class Scheduler

java.lang.Object

com.goldencode.p2j.scheduler.Scheduler

public final class Scheduler
extends java.lang.Object

Implements a cron-like scheduler, which can run P2J processes or arbitrary Java classes or methods.

The scheduler is configured in the scheduler container, which resides as a child of the server/<server-id> or the server/default nodes.

The scheduler node has a children nodes of class job. For each job node, the node's name represents the job name (which must be unique accross all jobs). Also, node-attribute nodes can be provided, with the following name:

• type, mandatory, case insensitive: string representation of the job type, following the description at the JobType enum.
• target, mandatory: the job target, which can be a process name, a java class or a java method (see javadoc for Job class for more details.
• enabled, mandatory: boolean value flag indicating if this job is enabled.
• mode, mandatory: string representation of the job mode, following the description at the JobMode enum.
• minute: the scheduled minute.
• hour: the scheduled hour.
• day-of-week: the scheduled day of the week.
• day-of-month: the scheduled day of the month.
• month: the scheduled month.

An example of a job starting an appserver at server startup:

 
   <node class="container" name="scheduler">
     <node class="job" name="start_appserver">
       <node-attribute name="type" value="process"/>
       <node-attribute name="target" value="appserver-name"/>
       <node-attribute name="enabled" value="TRUE"/>
       <node-attribute name="mode" value="now"/>
     </node>
   </node>
 
 

The JobType.INSTANCE can't be configured from the directory.

WARNING: when searching for the scheduler node, if there are both server/<server-id>/scheduler and server/default/scheduler, only the server's scheduler node will be used. Currently, there is no way of merging the default and server's scheduler.

When scheduling jobs for execution, each job must run under the server's context. This is not possible using the timer's threads. To solve this, the approach is to use the timer as a proxy which sends the jobs to the JobProcessor, which runs in its own thread, under the server's context. When the JobProcessor receives a new job, it will create a dedicated thread (with the server's context) and use that thread to execute the job.

See Also:

For more details about how jobs are scheduled.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static java.util.Map<java.lang.String,JobTask>	jobRegistry A registry with the enabled jobs, scheduled to be ran.
(package private) static java.util.Map<java.lang.String,Job>	jobs A map identifying all the available jobs.
private static CentralLogger	LOG Logger.
(package private) static JobProcessor	processor This instance will run on a dedicated thread, under the server's context, as job launching requires access to the directory.
(package private) static java.util.Timer	timer Job launcher timer.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Scheduler() Do not allow instances of this class.

Method Summary

Modifier and Type	Method and Description
static boolean	addJob(Job job) Add a new Job to the global registry.
static boolean	cancelJob(java.lang.String jobName) Cancel the job with the given name.
static Job	createJob(java.lang.String jobName, java.lang.String type, java.lang.String target, boolean enabled, java.lang.String mode, java.lang.String second, java.lang.String minute, java.lang.String hour, java.lang.String dayOfWeek, java.lang.String dayOfMonth, java.lang.String month, java.lang.String year) Validate the given configuration and create a new job.
static java.lang.String	getCronExpression(Job job) Build a cron expression following the CronExpression syntax, from the specified job.
static java.lang.String	getCronExpression(java.lang.String second, java.lang.String minute, java.lang.String hour, java.lang.String dayOfWeek, java.lang.String dayOfMonth, java.lang.String month, java.lang.String year) Build a cron expression following the CronExpression syntax, from the specified fields.
static Job	getJob(java.lang.String jobName) Get the Job with the given name.
private static long	getNextScheduleTime(Job job, java.lang.Long lastExecutionTime) Get the next job execution time.
(package private) static java.lang.Runnable	getRunner(Job job, java.util.Map<java.lang.String,java.lang.String> env) Get a runner to execute this job, depending on the job's type.
(package private) static void	initialize() Read the scheduler configuration and schedule the jobs.
static boolean	isScheduled(java.lang.String jobName) Check if the specified job is scheduled for execution.
static Job	removeJob(java.lang.String jobName) Remove the given job from the global job registry.
static long	scheduledExecutionTime(java.lang.String jobName) Get the next execution time for the given job.
static boolean	scheduleJob(java.lang.String jobName, java.lang.Long lastExecutionTime) Schedule a job for execution.
static boolean	scheduleJob(java.lang.String jobName, java.lang.Long lastExecutionTime, java.util.Map<?,?> env) Schedule a job for execution.
static void	scheduleJobs() Must be called only on server startup.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

private static final CentralLogger LOG

Logger.

jobs

static java.util.Map<java.lang.String,Job> jobs

A map identifying all the available jobs.

jobRegistry

static java.util.Map<java.lang.String,JobTask> jobRegistry

A registry with the enabled jobs, scheduled to be ran.

timer

static java.util.Timer timer

Job launcher timer. Will execute each job at its scheduled time.

processor

static final JobProcessor processor

This instance will run on a dedicated thread, under the server's context, as job launching requires access to the directory.

Constructor Detail

Scheduler

private Scheduler()

Do not allow instances of this class.

Method Detail

isScheduled

public static boolean isScheduled(java.lang.String jobName)

Check if the specified job is scheduled for execution.

Parameters:

jobName - The job name.

Returns:

See above.

scheduledExecutionTime

public static long scheduledExecutionTime(java.lang.String jobName)

Get the next execution time for the given job.

Parameters:

jobName - The job name.

Returns:

The next execution time or -1, if not scheduled.

removeJob

public static Job removeJob(java.lang.String jobName)

Remove the given job from the global job registry. Active jobs (which are scheduled for execution) can not be removed. Use cancelJob(java.lang.String) to cancel it first.

Parameters:

jobName - The job name.

Returns:

An Job instance with the removed job details or null if the job is scheduled for execution or it does not exist.

getJob

public static Job getJob(java.lang.String jobName)

Get the Job with the given name.

Parameters:

jobName - The job name.

Returns:

The Job instance or null if it does not exist.

addJob

public static boolean addJob(Job job)

Add a new Job to the global registry.

Parameters:

job - The job name. Must not already be in use for another job.

Returns:

true if the job was added. false if there is already a job with the same name,

cancelJob

public static boolean cancelJob(java.lang.String jobName)

Cancel the job with the given name.

Parameters:

jobName - The job name.

Returns:

true if the job was scheduled for execution and it was canceled.

scheduleJob

public static boolean scheduleJob(java.lang.String jobName,
                                  java.lang.Long lastExecutionTime)

Schedule a job for execution.

First, this will cancel any pending schedules and schedule it again, using the latest Job configuration.

Second, it will create a new JobTask which will be registered with the timer. At appropriate time, the timer will pick up the JobTask, use getRunner(com.goldencode.p2j.scheduler.Job, java.util.Map<java.lang.String, java.lang.String>) to create a new Runnable instance for this job and send it to the JobProcessor thread.

Parameters:

jobName - The job name.

lastExecutionTime - The last time the job was executed. null if this is the first time the job needs to run.

Returns:

true if the job was scheduled.

scheduleJob

public static boolean scheduleJob(java.lang.String jobName,
                                  java.lang.Long lastExecutionTime,
                                  java.util.Map<?,?> env)

Schedule a job for execution.

First, this will cancel any pending schedules and schedule it again, using the latest Job configuration.

Second, it will create a new JobTask which will be registered with the timer. At appropriate time, the timer will pick up the JobTask, use getRunner(com.goldencode.p2j.scheduler.Job, java.util.Map<java.lang.String, java.lang.String>) to create a new Runnable instance for this job and send it to the JobProcessor thread.

Parameters:

jobName - The job name.

lastExecutionTime - The last time the job was executed. null if this is the first time the job needs to run.

env - Map of environment properties, in the key=value form. For processes, these will be passed as JVM args.

Returns:

true if the job was scheduled.

getCronExpression

public static java.lang.String getCronExpression(Job job)

Build a cron expression following the CronExpression syntax, from the specified job.

Parameters:

job - Jhe job.

Returns:

A cron expression.

getCronExpression

public static java.lang.String getCronExpression(java.lang.String second,
                                                 java.lang.String minute,
                                                 java.lang.String hour,
                                                 java.lang.String dayOfWeek,
                                                 java.lang.String dayOfMonth,
                                                 java.lang.String month,
                                                 java.lang.String year)

Build a cron expression following the CronExpression syntax, from the specified fields.

Parameters:

second - The second when the job needs to be executed, following CronExpression syntax.

minute - The minute when the job needs to be executed, following CronExpression syntax.

hour - The hour when the job needs to be executed, following CronExpression syntax.

dayOfWeek - The day of the week when the job needs to be executed, following CronExpression syntax.

dayOfMonth - The day the month when the job needs to be executed, following CronExpression syntax.

month - The month when the job needs to be executed, following CronExpression syntax.

year - The year when the job needs to be executed, following CronExpression syntax.

Returns:

A cron expression.

createJob

public static Job createJob(java.lang.String jobName,
                            java.lang.String type,
                            java.lang.String target,
                            boolean enabled,
                            java.lang.String mode,
                            java.lang.String second,
                            java.lang.String minute,
                            java.lang.String hour,
                            java.lang.String dayOfWeek,
                            java.lang.String dayOfMonth,
                            java.lang.String month,
                            java.lang.String year)
                     throws JobValidationException

Validate the given configuration and create a new job.

Parameters:

jobName - The name of this job.

type - The type of this job, one of the JobType values.

target - The target of this job.

enabled - Flag indicating if this job is enabled.

mode - The execution mode of this job, one of the JobMode values.

second - The second when the job needs to be executed, following CronExpression syntax.

minute - The minute when the job needs to be executed, following CronExpression syntax.

hour - The hour when the job needs to be executed, following CronExpression syntax.

dayOfWeek - The day of the week when the job needs to be executed, following CronExpression syntax.

dayOfMonth - The day the month when the job needs to be executed, following CronExpression syntax.

month - The month when the job needs to be executed, following CronExpression syntax.

year - The year when the job needs to be executed, following CronExpression syntax.

Returns:

A new job instance.

Throws:

JobValidationException - If the configuration can't be validated. See the Job class javadoc for details about the validations being performed.

scheduleJobs

public static void scheduleJobs()

Must be called only on server startup. It starts new job processor thread using the server's context. Once the server's sockets have been connected, it reads the scheduler configuration and schedules the jobs.

initialize

static void initialize()

Read the scheduler configuration and schedule the jobs.

getRunner

static java.lang.Runnable getRunner(Job job,
                                    java.util.Map<java.lang.String,java.lang.String> env)

Get a runner to execute this job, depending on the job's type.

Parameters:

job - The job to be executed.

env - Map of environment properties, in the key=value form. For processes, these will be passed as JVM args.

Returns:

A runnable instance for this job.

getNextScheduleTime

private static long getNextScheduleTime(Job job,
                                        java.lang.Long lastExecutionTime)
                                 throws JobValidationException

Get the next job execution time.

Parameters:

job - The job name.

lastExecutionTime - The last time the job was executed, in millis. If null, it means it is the first execution and the current time will be used.

Returns:

The next execution time, in millis, or -1 if the job's cron expression could not be parsed.

Throws:

JobValidationException