|
Oracle® Application Server Containers for J2EE Job Scheduler Developer's Guide
10g Release 3 (10.1.3) B15876-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE Job Scheduler Developer's Guide
10g Release 3 (10.1.3) B15876-01 |
|
|
Previous |
Next |
This chapter describes how to create jobs based on schedules. The following topics are covered:
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.
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);
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).
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);
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);
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);
This section discusses retry period and execution threshold, and provides an example of each in relation to a scheduled job.
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:
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).
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:
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.
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);
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.
