Package com.sapportals.wcm.service.scheduler

Provides a service that controls the execution of tasks.

See:
Description

Interface Summary

ISchedulerEntry	Scheduler entries contain data for scheduler tasks.
ISchedulerEntryFactory	Deprecated. since KM5.0SP6.
ISchedulerEntryList	Deprecated. since KM 5.0 SP6
ISchedulerEntryListIterator	Deprecated. since KM 5.0 SP6
ISchedulerService	The scheduler service for the WCM.
ISchedulerTask	The task to be run by the scheduler.
ISchedulerTime	The times for a scheduler.
ISchedulerTimeList	Deprecated. since KM6.0SP1.
ISchedulerTimeListIterator	Deprecated. since KM5.0SP6.
ISchedulerTimeTable	Timetables for the scheduler.
ISequence	Specifies a sequence of scheduler entries.

Class Summary

SchedulerServiceFactory

The scheduler service factory.

Package com.sapportals.wcm.service.scheduler Description

Provides a service that controls the execution of tasks.

Package Specification

Purpose
Detailed Concept
Interfaces and Classes
Code Samples
Configuration
Implementation Notes

Purpose

The scheduler is a service that manages the execution of tasks for applications. An application can register a task at the scheduler and specify a time when it must be performed. The scheduler then ensures that the task is started at the right time and monitors its execution.

The service is particularly useful for tasks that have to be performed regularly. For example, the subscription service uses the scheduler to ensure that directories containing relevant documents are crawled at regular intervals.

In the following, a scheduled task that has to be performed at a specific time is called a job.

Detailed Concept

The scheduler offers two types of support. It triggers the execution of jobs at the time when they are scheduled and, in addition, manages all the jobs that are registered for execution. This means it is responsible for registering, modifying, monitoring and deleting jobs. When it monitors the status of running jobs, it can stop, suspend or resume jobs. If several jobs are scheduled to run at the same time, it checks their priority and decides which one should be executed first.

From a technical perspective, the scheduler is an implementation of the ISchedulerService interface. The interface provides methods to manage a list of jobs and to start each one at a predefined time. Each job in the list is defined with the help of an ISchedulerEntry object which stores the essential information about the job. This includes:

• The unique job ID
• The task that is to be performed.
  A task is defined by an implementation of the ISchedulerTask interface.
• The times at which the task is to be executed.
  The times are stored in an ISchedulerTimeTable object . Each entry in the timetable specifies a particular time when the job must be executed and is represented by an ISchedulerTime object.
• The job priority expressed as a digit.
  When several jobs are scheduled for the same time, the priority indicates which one must be executed first.
• A list of CM systems where the task can be performed in a cluster installation.

Note:
If a CM system is part of a cluster installation, at least one CM system must be selected in the list of CM systems. If the list is empty, the scheduler does not perform the task. If one or ore systems are selected, the scheduler services of all listed systems will perform the task.
If the CM system is not clustered, the scheduler performs the task, no matter if the list is empty or not.

The scheduler regularly checks whether any of the jobs that it is responsible for have to be executed. For this reason it must be able to continuously access information about all registered jobs and their execution time.

Interfaces and Classes

The main interfaces of the scheduler service are:

• ISchedulerService
• It defines the most important methods that are required by an application that wants to use the scheduler. It offers methods to create and manage scheduled jobs.
• ISchedulerEntry
  Provides methods to define and manipulate individual jobs. It enables the definition of job details and access to information about an existing job or the status of a job.
• ISchedulerTimeTable and ISchedulerTime
  The ISchedulerTimeTable interface provides methods to maintain the timetable that stores the execution times for a job. It can be used to add entries to the timetable or retrieve information like the start and expiry date of the job. Each entry in the timetable is represented by an ISchedulerTime object. This is instantiated with the createTimeWildcard method of the ISchedulerService and can then be used to set the execution times for a job. The times are set using the fields defined in java.util.Calendar and integers that represent the day of the year, month, week, hour and so on.
  An ISchedulerTime is different to a calendar time because it does not refer to a specific time, but to a recurring time.
  For example, to specify that a job must run every Friday at 10pm using the ISchedulerTime interface, you specify the calendar field and integers as follows:
  set(Calendar.FRIDAY, 10, 0);
• ISchedulerTask
  An application that wants to use the scheduler service must define the task that is to be executed by implementing the interface. The interface only defines one method:
  run(java.lang.String id, java.util.Properties properties)
• ISequence
  This is an additional order relation to perfom scheduler tasks at a certain time only after a previous sequenced task was performed before. Each scheduler entry has to be unique in this sequence.
  

The diagram shows the interfaces described above:

Code Samples

If an application wants to use the scheduler service, it can access most of the available functions via the ISchedulerService interface. However, in addition, it must define the task that is to be executed by implementing the ISchedulerTask interface. In summary, an application that wants to use the scheduler must:

1. Define a task by implementing the ISchedulerTask interface
2. Define the time when the task must be executed using the createTimeTable and createTimeWildcard methods of the ISchedulerService interface.
3. Define the job using the createSchedulerEntry method of the ISchedulerService interface. This requires the ID of the job, its priority, the task that is to be executed, the timetable and any properties that have been defined.

The code sample schedules a task to run every hour:

  ISchedulerService service = ResourceFactory.getInstance().getServiceFactory().getService(IServiceTypesConst.SCHEDULER_SERVICE );
  ISchedulerTimeTable timeTable = service.createTimeTable();
  ISchedulerTime time = service.createTimeWildcard();

  // start every hour
  time.set( Calendar.HOUR_OF_DAY, 1 );
  time.set( Calendar.MINUTE, 0 );

  timeTable.addToTable( time );

  Properties properties = new Properties();
  properties.setProperty( "rid", "sampleURI" );

  service.createSchedulerEntry("sampleID", 1, new SchedulerTaskExample(), timeTable, properties );

Configuration

The scheduler can be configured with the parameters shown in the table.
The parameters can be set with the help of the user interface of the Content Management configuration framework.
For more information, see the documentation Administering Content Management.

The parameters in the table that are not required have default values that are used if no value is specified.

Scheduler Service

Parameter	Required	Description
entries	yes/no	A list of ISchedulerEntry objects

Scheduler Task Entry

Parameter	Required	Description
name	yes	The unique ID of this entry
priority	yes	The priority of the task
timetable	no	An com.sapportals.wcm.service.scheduler.ITimeTable object
task	yes	An ISchedulerTask implementation.
cmsystems	no	A list of possible CM Systems where the task can be executed when running in a cluster
properties	no	A set of properties depending on the ISchedulerTask implementation.

Scheduler Time

Parameter	Required	Description
year	no	The year between 2000 and 2025. No setting means every year.
month	no	The month between 1 and 12. No setting means every month.
weekofmonth	no	The week of the month between 1 and 5.
monthday	no	The day of the month (when this property overrides the weekofmonth setting )
weekday	no	The day of the week from 1 (Monday) to 7 (Sunday)
hour	no	The hour of the day between 0 and 23.
minute	no	The minute of an hour between 0 and 59. No setting means every minute.
cmsystems	no	A list of CM Systems where the task can be executed in a cluster at the specified time. The list must be a subset of the list of CM systems in the assigned scheduler entry object.

Sample Configuration for Scheduler Time

The following settings show schedule entry that triggers the execution of the task once a year, every full hour on the first Sunday in May. If no parameters are set in the scheduler entry, the task runs every minute.

Parameter	Value
month	5 (May)
weekofmonth	1
weekday	7 (Sunday)
minute	0

Implementation Notes

The sequence diagram shows the actions that are necessary to schedule a task.

Note that the scheduler uses the configuration framework as its persistence layer. All entries created at runtime can be edited via the user interface of the configuration framework.