Job Scheduling Through the Scheduler API 

Introduction and Scope

The purpose of this section is to outline the aspects of scheduling a job programmatically from a development point of  view.

The section introduces the SchedulerTask class and the related classes and methods from the Scheduler API necessary for creating a scheduler task. It also provides a description of the Scheduler API, outlining the possible ways to set various types of recurring and cron start conditions to jobs.

For the reference documentation of the Scheduler API, see the JavaDoc at http://help.sap.com/javadocs/nwce/current/sc/index.html,  the com.sap.scheduler.api package.

Currently, with the NetWeaver Scheduler for Java, you cannot schedule a job for immediate execution.

Use

Scheduler API

Currently, you can schedule jobs only programmatically from within applications by using the Scheduler API provided by the NetWeaver Scheduler for Java.

To be able to use the Scheduler API, you need a JNDI reference to the Scheduler. See Getting a JNDI Reference to the Scheduler API

Scheduler Task

You use a scheduler task to schedule the execution of job definition instances (jobs) in time (time-based scheduling). Conversely, you schedule jobs by creating a scheduler task that instructs the NetWeaver Scheduler for Java which job definition to instantiate and run when and with what parameters.

You may think of a scheduler task as of a “time table”, which contains the schedule for the execution times of each job definition instance.

You create a scheduler task by instantiating the SchedulerTask class.

Integration

The Scheduler API is a local interface. You can schedule jobs only from applications deployed on AS Java. You cannot access the API remotely.

Prerequisites

You create a scheduler task for a job definition. That is why, before you create a scheduler task, make sure that the job definition, whose instances you want to schedule, is deployed on the server.

Structure and Features

Scheduler API

The Scheduler API declares all the classes and methods you need in order to schedule job definition instances with time-based start conditions. The rest of this section provides an outline of the SchedulerTask class as well as the use cases for the different start conditions you can apply to job definition instances.

Scheduler Task

The SchedulerTask class declares the following members:

●      SchedulerTaskID

An ID for the scheduler task which is a GUID. Currently, you have to create the ID of the scheduler task manually by invoking the SchedulerTaskID.newID()method.

●      JobDefinitionID

The ID of the job definition whose instances you want to schedule. You pass the job definition ID to the scheduler task by invoking the getJobDefinitionId method.

●      JobParameter

If you have used parameters with direction IN or INOUT in your job definition, you have to create JobParameter objects to specify values for those parameters.

See Job Parameters and Parameter Properties

●      RecurringEntry

You use instances of the RecurringEntry class to define a schedule for recurrent job execution (once or periodically).

The Scheduler API provides different scenarios for defining recurrent job execution. See Scheduling Jobs with Recurrent Start Conditions

●      CronEntry

You use instances of the CronEntry class to define a schedule for job execution with execution times relative to the start/end of the month.

See Scheduling Jobs with Cron Start Conditions

●      Filter

By using the Filter class, you can instruct the scheduler not to execute jobs within a specified time frame. Instances of this class define the start and end point of the time frame, in which you do not want jobs to run.

See Excluding Scheduled Job Executions from a Scheduler Task

●      retentionPeriod

A variable for the number of days you want job logs to remain in the database. You specify the default value for the retention period in the job-definition.xml. In the scheduler task, you can overwrite the default value.

You schedule the SchedulerTask by invoking the schedule() method.

In the same SchedulerTaskobject, you can create multiple RecurringEntry and CronEntry instances. In this way you can set recurring and cron start conditions for the same job definition.

You can define different parameter values for each RecurringEntry and CronEntry belonging to the same SchedulerTaskobject. You do so by creating different JobParameter objects for each Regurring or CronEntry. As a result, instances of the same job definition, that are scheduled with the same SchedulerTask, run with different parameters along their recurrent or cron schedule.

For example, you have a definition of a job that backs up files. You can schedule backup jobs to run every day at 6 PM (recurrent execution) and backup one set of files, as well as to run every weekend at 10 PM (cron execution) to backup another set of files.

If a job instance fails to complete four times in a row, the corresponding scheduler task is put on hold.

Scheduler Time

SchedulerTime is an immutable class, and you use instances of this class to define the points in time you need for the job schedule. The most common uses of SchedulerTime are to define the start and the end of the time frame of a RecurringEntry or of a Filter object.

When you create a SchedulerTimeinstance, you pass a Calendar instance (java.util.Calendar) to it or time in milliseconds from the Epoch.

SchedulerTime also defines a time zone which allows you to create schedules relative to different time zones.

 

For a step-by-step guide on scheduling a job definition, see Scheduling the Hello Job in the Creating and Scheduling Your First Job section.