Skip Headers

Oracle® Application Server Containers for J2EE Job Scheduler Developer's Guide 10g Release 3 (10.1.3) B15876-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 3 Oracle Application Server Containers for J2EE Scheduling Options

This chapter describes how to create jobs based on schedules. The following topics are covered:

- Schedule-Based Jobs

- Retry Period and Execution Threshold

- Frequently Asked Questions About iCalendar and Execution Threshold

## 3.1 Schedule-Based Jobs

This section contains descriptions and some job implementation examples for schedule-based jobs.

A schedule-based (or schedule-driven) job is associated with a schedule, meaning that the job is time-based. In contrast, a job associated with a trigger is event-based and typically driven by events initiated by the application. When a schedule expires, a timeout is generated, which is used to trigger the execution of the job.

There are two primary types of schedule-based jobs:

- Single-action schedules.

  This type of schedule has a single expiration, and should be used when a job is run only once.

- Repeating Schedules.

  This type of schedule has multiple expirations, and should be used when a job is run repeatedly.

### 3.1.1 Single-Action Schedules

Single-action schedules are implemented with the `oracle.ias.scheduler.Schedule` class. This type of schedule has a single attribute called `expiration`, which is the initial expiration of the schedule.

Example 3-1 Submitting a Job at a Specific Time

In continuing the example started in Example 2-1, the developer and administrator need to run the backup jobs on an as-needed basis. To do this, a single-action schedule will be used. The following code example shows how the job is set up with a single-action schedule and submitted:

    // set up the properties
    java.util.Properties properties = new Properties();
    properties.put("SourceDirectory","/mnt/data");
    properties.put("DestinationDirectory","/mnt/backup");

    // set up the schedule, single-action at midnight
    Schedule schedule = new Schedule();
    Calendar midnight = Calendar.getInstance();
    midnight.set(Calendar.HOUR_OF_DAY,24);
    midnight.set(Calendar.MINUTE,0);
    midnight.set(Calendar.SECOND,0);
    schedule.setExpiration(midnight);

    // submit the job
    scheduler.add("file backup job, runs at midnight",
                  new BackupJob().getClass().getName(),
                  schedule,
                  properties);

### 3.1.2 Repeating Schedules

There are three types of repeating schedules:

- Fixed-interval schedule

  This type of schedule uses the `oracle.ias.scheduler.IntervalSchedule` class for repeating jobs with a fixed interval (for example, a job that runs once per week, every friday at midnight).

- Fixed-delay schedule

  This type of schedule uses the `oracle.ias.scheduler.IntervalSchedule` class for repeating jobs with a fixed interval between job executions (for example, a job where the end of one job execution and the start of the next job execution is one week).

- iCalendar recurrence schedule

  This type of schedule uses the `oracle.ias.scheduler.RecurSchedule` class for repeating jobs with a schedule that does not repeat at regular intervals (for example, the first day of every month, which is not a fixed interval because the number of days in each month varies).

#### 3.1.2.1 Fixed-Interval Schedules

A fixed-interval schedule has the following attributes:

Attribute | Description
--- | ---
`expiration` | Initial expiration
`interval` | Interval (specified in milliseconds) between expirations
`end date` | Date and time at which the schedule ends

Example 3-2 Submitting a Repeating Job with a Fixed-Interval Schedule

To expand on Example 3-1, suppose the developer and administrator need to run the backup job on a weekly basis. To do this, a fixed-interval repeating schedule will be used, as shown in the following code example:

    // set up the properties
    java.util.Properties properties = new Properties();
    properties.put("SourceDirectory","/mnt/data");
    properties.put("DestinationDirectory","/mnt/backup");

    // set up the schedule, repeats every week
    IntervalSchedule schedule = new IntervalSchedule();
    schedule.setInterval(IntervalSchedule.EVERY_WEEK);

    // submit the job
    scheduler.add("file backup job, runs at midnight",
                  new BackupJob().getClass().getName(),
                  schedule,
                  properties);

#### 3.1.2.2 Fixed-Delay Schedules

To expand on Example 3-1, suppose the developer and administrator need to run the backup job on a more regular basis (for example, one week between each backup). To do this, a fixed-delay repeating schedule will be used, as shown in the following code example:

Example 3-3 Submitting a Repeating Job with a Fixed-Delay Schedule

    // set up the properties
    java.util.Properties properties = new Properties();
    properties.put("SourceDirectory","/mnt/data");
    properties.put("DestinationDirectory","/mnt/backup");

    // set up the schedule, repeats every week
    IntervalSchedule schedule = new IntervalSchedule();
    schedule.setInterval(IntervalSchedule.EVERY_WEEK);
    schedule.setFixedDelay(true);

    // submit the job
    scheduler.add("file backup job, runs at midnight",
                  new BackupJob().getClass().getName(),
                  schedule,
                  properties);

#### 3.1.2.3 iCalendar Recurrence Schedules

The attributes for an iCalendar recurrence schedule are based on RFC 2445, "Internet Calendaring and Scheduling Core Object Specification (iCalendar)." For more information, see Appendix A.

Example 3-4 Submitting a Repeating Job with an iCalendar Recurrence Schedule

To expand on Example 3-1, suppose the developer and administrator need to run the backup job on a monthly basis, on the first of each month. To do this, an iCalendar recurrence schedule will be used, as shown in the following code example:

    // set up the properties
    java.util.Properties properties = new Properties();
    properties.put("SourceDirectory","/mnt/data");
    properties.put("DestinationDirectory","/mnt/backup");

    // set up the schedule, repeats on the first day of every month
    RecurSchedule schedule = new RecurSchedule("freq=monthly;bymonthday=1;");

    // submit the job
    scheduler.add("file backup job, runs at midnight",
                  new BackupJob().getClass().getName(),
                  schedule,
                  properties);

## 3.2 Retry Period and Execution Threshold

This section discusses retry period and execution threshold, and provides an example of each in relation to a scheduled job.

### 3.2.1 Retry Period

A job execution that fails may be retried after a time period. This time period is called the retry period and is specified in milliseconds. If this period is not set as part of the job definition, the job's executions will not be retried. For example, consider Figure 3-1:

Figure 3-1 Retry Period

Description of "Figure 3-1 Retry Period"

This illustration depicts a repeating schedule, where the job should run each night at midnight. The retry period is three hours, meaning that if the initial job execution fails, the job will be retried again three hours later, at 3:00a.m. If the job execution fails again at 3:00a.m., the job execution for this particular instance is discarded, and another attempt will not be made until the next scheduled run-time (in this case, midnight the following night).

### 3.2.2 Execution Threshold

If a job's scheduled execution is delayed beyond a specified time threshold, then the job execution will be discarded. This time threshold is called the execution threshold and is specified in milliseconds. If an execution threshold is not specified as part of job's definition, resultant job executions will not be constrained by an execution threshold. For example, consider Figure 3-2:

Figure 3-2 Execution Threshold

Description of "Figure 3-2 Execution Threshold"

The job execution is scheduled to run at midnight on Monday, and the execution threshold is 6 hours. The job execution would be discarded if it did not run by 6:00a.m. Monday.

### 3.2.3 Submitting a Job with a Retry Period and Execution Threshold

To further expand on Example 3-1, a retry period and execution threshold were added to Example 3-5. In this example, if the job's executions do not occur within 30 seconds (execution threshold) of the scheduled time, they will be discarded. If the executions do occur, but fail, they will be retried 3 seconds (retry period) later.

Example 3-5 Submitting a Job with a Retry Period and Execution Threshold

    // set up the properties
    java.util.Properties properties = new Properties();
    properties.put("SourceDirectory","/mnt/data");
    properties.put("DestinationDirectory","/mnt/backup");

    // set up the schedule, repeats every week
    IntervalSchedule schedule = new IntervalSchedule();
    schedule.setInterval(IntervalSchedule.EVERY_WEEK);

    // submit the job
    scheduler.add("file backup job, runs at midnight",
                  new BackupJob().getClass().getName(),
                  schedule,
                  properties,
                  3000,
                  30000);

## 3.3 Frequently Asked Questions About iCalendar and Execution Threshold

Does Job Scheduler check the execution threshold if the job trigger is something other than a timeout?

No. Because the execution threshold is based on time, notifications other than timeouts do not cause Job Scheduler to check the execution threshold.

Can I update the execution threshold or retry period for a job?

Currently, this is not possible, because a job is configured with these parameters at creation time.

Can a fixed-delay schedule be submitted in conjunction with a trigger in a job definition?

No. The period for a fixed-delay schedule is based on the completion of the previous job execution. When a trigger is used, this period cannot be determined because it is dependent on the receipt of one or more notifications as specified by the trigger.