Show TOC

Job Scheduling Through the Scheduler APILocate this document in the navigation structure

Use

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.

Note

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

Scheduler API

Currently, you can schedule jobs only programmatically from within applications by using the Scheduler API provided by the SAP 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 SAP 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 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 Cron Entry class to define a schedule for job execution with execution times relative to the start of the month, week, day, and hour.

    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.

If you want to schedule tasks with planned execution close to or coinciding with the moment of scheduling, call the schedulenofail() method.

Note

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

All jobs that are scheduled by a single SchedulerTask object have the same parameters, as parameters are a property of the task.

For example, you have a definition of a job that backs up files. You can set up a task that schedules a backup job to run every day at 6 PM and backup one set of files. You do so by specifying appropriate parameters. If you want to automatically back up another set of files, you will have to set up another task with different parameters.

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 SchedulerTime instance, you pass a Date instance ( java.util. Date ) 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.