Excluding Scheduled Job Executions from a Scheduler Task

Use

This section outlines the attributes and the use of the Filter class and shows how you can create and apply filters to a scheduler task.

Filters

The Filter class has two attributes - start time and end time - which specify the boundaries of a time frame.

You use Filter objects in a scheduler task to instruct the SAP NetWeaver Scheduler for Java not to execute the jobs that fall into the specified time frame. For example, you can instruct the scheduler not to run a particular job on holidays.

Note

In this document, the term filter and Filter object are used in the sense of a time frame within which the Scheduler is instructed not to execute instances of a job definition scheduled by a scheduler task.

A filter is bound to a scheduler task, not to a particular RecurringEntry or CronEntry in a scheduler task. Conversely, a filter applies to the whole task, not to the individual RecurringEntry and/ or CronEntry objects in it. In effect, in a scheduler task containing multiple RecurringEntry and/ or CronEntry objects, you cannot filter out the job executions of just one of those RecurringEntry and/ or CronEntry objects.

You can apply multiple filters to the same scheduler task. To apply the same filter to all scheduler tasks, and thus instruct the scheduler not to execute any tasks at all within the time frame, you have to add the same Filter object to each scheduler task individually.

Applying Filters

The static method createSchedulerTask(...) of the SchedulerTask interface allows you to apply filters when creating a SchedulerTask .

Sample Code

                  createSchedulerTask(JobDefinitionID jobDefinitionId, JobParameter[] jobParameters, 
RecurringEntry[] recs, CronEntry[] crons, Filter[] filters, int retentionPeriod, String name, 
String description, String customData)

When you do not provide this method with filters, you cannot add filters to the obtained SchedulerTask object anymore. You can rather add filters to the task after scheduling the SchedulerTask object with the schedule(SchedulerTask task) method of the Scheduler interface. The Scheduler interface provides the methods:

addFilters(SchedulerTaskID id, Filter[] f) - adds a filter to the filters already added to the task
setFilters(SchedulerTaskID id, Filter[] f) - removes the current filters from the task and applies the filters you pass as arguments of the method

The following snippet shows how you can create and add filters to a scheduler task.

In the example we use a scheduler task that contains a RecurringEntry that schedules a job every hour from the current time on. Observe that the first execution time is ignored, because it is not in the future when the task is scheduled.

For information how to get the JobDefinition helloJobDef and the JobParameter[] param that are used in the method createSchedulerTask (...) go to Creating a Scheduler Task for the HelloJob .

Sample Code

                  //Create SchedulerTime object with the current time
SchedulerTime startTime = new SchedulerTime();

// Create recurring entry (from now on every hour)
RecurringEntry[] recEntry = 
        {new RecurringEntry(startTime, (long) 3600*1000)};

//Create SchedulerTime instances for the start and the end
//of the filters.
Calendar calendar = Calendar.getInstance();
calendar.add(Calendar.MINUTE, 59);
SchedulerTime filter1StartTime = 
        new SchedulerTime(calendar.getTime(), TimeZone.getDefault());
calendar.add(Calendar.MINUTE, 2);               
SchedulerTime filter1EndTime = 
        new SchedulerTime(calendar.getTime(), TimeZone.getDefault());

calendar.add(Calendar.MINUTE, 58);                      
SchedulerTime filter2StartTime = 
        new SchedulerTime(calendar.getTime(), TimeZone.getDefault());
calendar.add(Calendar.MINUTE, 2);
SchedulerTime filter2EndTime = 
        new SchedulerTime(calendar.getTime(), TimeZone.getDefault());

// Create the filters
Filter[] myFilters1 = {new Filter(filter1StartTime, filter1EndTime)};
Filter[] myFilters2 = {new Filter(filter2StartTime, filter2EndTime)};

// Create SchedulerTask only with filter1
SchedulerTask task = SchedulerTask.createSchedulerTask(
        helloJobDef.getJobDefinitionId(), param, recEntry, 
        null, myFilters1, -2, "Hellojob Taskname", 
        "HelloJob Task Description", null);

// Schedule the task
try {
        scheduler.schedule(task);
} catch (TaskValidationException e) {
        // some Exception handling
}

// Add filter2
try {
        scheduler.addFilters(task.getTaskId(), myFilters2);
} catch (TaskDoesNotExistException e) {
        // some Exception handling
}