You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by jv...@apache.org on 2001/12/17 16:04:56 UTC
cvs commit: jakarta-turbine-fulcrum/xdocs/howto scheduler-service.xml
jvanzyl 01/12/17 07:04:56
Added: xdocs/howto scheduler-service.xml
Log:
- moving the scheduler doc/howto into fulcrum and adding a blurb about
the non-persistent scheduler to try and help a user get it running.
Revision Changes Path
1.1 jakarta-turbine-fulcrum/xdocs/howto/scheduler-service.xml
Index: scheduler-service.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Turbine Services - Scheduler Service</title>
<author email="jvanzyl@apache.org">Jason van Zyl</author>
</properties>
<body>
<section name="Scheduler Service">
<p>
The Scheduler is modeled after Unix Cron. The Scheduler runs as a background
process that executes timed scheduled tasks independently of HTTP requests.
Tasks are stored in the database in the TURBINE_SCHEDULED_JOB table and once
entered in the database are loaded automatically when Turbine initializes.
</p>
<p>
For the Scheduler to load classes that extend the ScheduledJob Class,
the scheduler needs to be enabled via the TurbineResources.properties
file, where the directive scheduler.enabled needs to be set to true.
</p>
</section>
<section name="Configuration">
<source><![CDATA[
# -------------------------------------------------------------------
#
# S E R V I C E S
#
# -------------------------------------------------------------------
# Classes for Turbine Services should be defined here.
# Format: services.[name].classname=[implementing class]
#
# To specify properties of a service use the following syntax:
# service.[name].[property]=[value]
services.SchedulerService.classname=org.apache.turbine.services.schedule.TurbineSchedulerService
.
.
.
# -------------------------------------------------------------------
#
# S C H E D U L E R S E R V I C E
#
# -------------------------------------------------------------------
#
# Set enabled to true to start the scheduler.
#
# Default = false
#
scheduler.enabled=true
]]></source>
</section>
<section name="Usage">
<p>
To create an object that takes advantage of the Schedule Service, the task
to be executed will need to be embedded in the run() method of an object
which extends the ScheduledJob Class. For instance:
</p>
<source><![CDATA[
package com.mycompany.modules.scheduledjobs;
//JDK
import java.util.Date;
//Turbine
import org.apache.turbine.modules.ScheduledJob;
import org.apache.turbine.services.schedule.JobEntry;
import org.apache.turbine.util.Log;
public class SimpleScheduledTask extends ScheduledJob
{
private int taskcount = 0;
/**
* Constructor
*/
public SimpleScheduledTask()
{
//do Task initialization here
}
/**
* Run the Jobentry from the scheduler queue.
* From ScheduledJob.
*
* @param job The job to run.
*/
public void run( JobEntry job ) throws Exception
{
Log.note("Scheduled job " + job.getId() + " : " +
"task: " + job.getTask() + " ran @: " +
new Date(System.currentTimeMillis()).toString() +
" taskcount " + taskcount);
//iterate the task counter
taskcount++;
}
}
]]></source>
<p>
The SimpleScheduledTask object makes an entry into the turbine.log each
time the Task is run by the Schedule Service. The JobEntry object carries the
information the Service uses to determine the frequency of the Task.
Note that the object is in the com.mycompany.modules. This assumes that the
package com.mycompany.modules is in the Turbine module path, which is in the
module.packages directive in the TurbineResources.properties.
The ScheduledJobLoader object loads the Task upon Turbine initilization also
searches for a <i>scheduledjobs</i> package which contains the Task object.
</p>
<p>
Control of the time between, or to, execution of the Task, is controlled by
the JobEntry object. The JobEntry serves as a wrapper for the scheduled task.
The constructor is as follows:
</p>
<source><![CDATA[
public JobEntry(int sec, int min, int hour,
int wd, int day_mo, String task)
throws Exception
]]></source>
<p>
The granularity of the Task's next execution can be controlled to the level
of seconds. In the above constructor, sec represents the seconds with a valid
range of 0-59, min represents the minutes with a valid range of 0-59,
hour represents the hours with a valid range of 0-23, wd is the day of the
week with a valid range of 1-7, day_mo is the day of the month with a valid
range of 1-31 and task is the name of the object. The JobEntry constructor
allows for the Task to be run at a certain point in time. For example:
</p>
<source><![CDATA[
JobEntry je = new JobEntry(0,25,-1,-1,-1,"SimpleScheduledTask");
o run every 25 minutes.
JobEntry je = new JobEntry(0,0,8,-1,15,"SimpleScheduledTask");
o run at 8:00am on the 15th of the month every month.
]]></source>
<p>
The Schedule Service will only execute Tasks at Turbine Initialization that
are present in the Database. To add a Task to the Database we need to set up
an Action class that can be accessed from a template with:
</p>
<source><![CDATA[
$page.SetTitle("SimpleScheduleTask Starter Page")
Set Values for SimpleScheduleTask and then start it for the first time.
<br/>
<form>
<input type="hidden" name="action" value="SchedulerStart" />
<input type="text" name="second" size="20" /> : seconds (0-59)<br />
<input type="text" name="minute" size="20" /> : minutes (0-59)<br />
<input type="text" name="hour" size="20" /> : hours (0-23)<br />
<input type="text" name="weekday" size="20" /> : Day of the Week (1-7)<br />
<input type="text" name="day_of_month" size="20" /> Day of the Month (1-31)<br />
<input type="text" name="task" value="SimpleSchedulerTask" /> : The Task being scheduled. <br />
<input type="text" name="email" /> : Email<br />
</form>
]]></source>
<p>
and the appropriate Action class:
</p>
<source><![CDATA[
package com.mycompany.modules.actions;
//Turbine
import org.apache.turbine.util.RunData;
import org.apache.turbine.services.schedule.JobEntry;
import org.apache.turbine.services.schedule.ScheduleService;
import org.apache.turbine.modules.actions.VelocityAction;
public class SchedulerStart extends VelocityAction
{
public void doPerform(RunData data) throws Exception
{
ParameterParser params = data.getParameters();
int second = params.getInt("second",-1);
int minute = params.getInt("minute",-1);
int hour = params.getInt("hour",-1);
int weekday = params.getInt("weekday",-1);
int dom = params.getInt("day_of_month",-1);
String task = params.getString("task","");
String email = params.getString("email","");
try
{
//access the service singleton
ScheduleService ss = (ScheduleService)TurbineServices
.getInstance().getService(ScheduleService.SERVICE_NAME);
//create a new JobEntry with the time constraints from
//the template as the arguments
JobEntry je = new JobEntry(second,minute,hour,weekday,dom,task);
//set the email for notification
je.setEmail(email);
//add the job to the queue
ss.addJob(je);
//set the Message
data.setMessage("Task " + task + "started successfully");
}
catch (Exception e)
{
//set the Message
data.setMessage("Task " + task + " failed to start!");
}
setTemplate(schedule,SchedulerStatus.vm);
}
}
]]></source>
<p>
The SchedulerStart Action class initializes the Scheduler for that Task.
The TurbineSchedulerService object exposes other methods that allow the
Scheduler process to be monitored, such as getJob(int oid),
removeJob(JobEntry je), updateJob(JobEntry je), listJobs(). As well as
methods which allow the Scheduler thread to be accessed.
</p>
<p>
The Scheduler Service uses a seperate thread for each Task it runs to ensure
that every job runs on time. It's the programmer's responsibility to ensure
that proper precautions to handle issues such as synchronization and long
running jobs. As always, check through the relevant Javadocs and source code
for more details on the Scheduler Service.
</p>
</section>
<section name="Properties Based Scheduler">
<p>
Service for a cron like scheduler that uses the
TurbineResources.properties file instead of the database.
The methods that operate on jobs ( get,add,update,remove )
only operate on the queue in memory and changes are not reflected
to the properties file which was used to initilize the jobs.
An example is given below. The job names are the class names that
extend ScheduledJob.
</p>
<p>
Here is a sample configuration that you might add to your
Fulcrum.properties to use the non persistent scheduler:
</p>
<source><![CDATA[
services.SchedulerService.scheduler.jobs=scheduledJobName,scheduledJobName2
services.SchedulerService.scheduler.job.scheduledJobName.ID=1
services.SchedulerService.scheduler.job.scheduledJobName.SECOND=-1
services.SchedulerService.scheduler.job.scheduledJobName.MINUTE=-1
services.SchedulerService.scheduler.job.scheduledJobName.HOUR=7
services.SchedulerService.scheduler.job.scheduledJobName.WEEKDAY=-1
services.SchedulerService.scheduler.job.scheduledJobName.DAY_OF_MONTH=-1
services.SchedulerService.scheduler.job.scheduledJobName2.ID=1
services.SchedulerService.scheduler.job.scheduledJobName2.SECOND=-1
services.SchedulerService.scheduler.job.scheduledJobName2.MINUTE=-1
services.SchedulerService.scheduler.job.scheduledJobName2.HOUR=7
services.SchedulerService.scheduler.job.scheduledJobName2.WEEKDAY=-1
services.SchedulerService.scheduler.job.scheduledJobName2.DAY_OF_MONTH=-1
]]></source>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>