B Oracle Application Server Containers for J2EE Semantics

This appendix summarizes the differences in semantics among several closely related terms: remove, pause, cancel, retry, replay, and execution threshold. The following topics are covered:

Semantics
Job Precedence

B.1 Semantics

This section provides a summary of the differences in semantics of the various job operations. Figure B-1 illustrates the various job operations:

Figure B-1 Job Scheduler Semantics

Description of "Figure B-1 Job Scheduler Semantics"

Here is a job with a repeating schedule. The job is scheduled to run each night at midnight, with a retry period of 1 hour, an execution threshold of 6 hours, and a blackout window from 6:00 a.m. to midnight each day.

Removing a Job

Removing a job deletes the job definition, thus preventing the job from being run in the future. For example, if a job were removed at 2:00 a.m. on Monday, all future scheduled executions would be removed, and the job would not be run again on Tuesday, or Wednesday, or at any point in the future. If a job execution was running at the time the job was removed, the job execution would finish before the job was removed. To immediately stop a job execution that is running, you must cancel the job.

For more information about removing jobs, see Section 2.3.

Canceling a Job

Canceling a job stops the job execution while it is running. This is the only way to stop a job execution that is currently running. If you want to re-run the canceled job execution at some future point, you must specify a retry period.

For more information about canceling jobs, see Chapter 6.

Pausing a Job

Pausing a job causes future scheduled job executions to be skipped until the point at which the job is resumed. For example, if you pause a job at 2:00 a.m. on Monday, and resume the job at 2:00 a.m. on Tuesday, then the scheduled job execution at midnight on Tuesday would be skipped.

If you want the skipped job execution to run, set replay to true when you resume the job and the skipped job execution will be run when the job is resumed. If replay is set to false, then the skipped job execution is ignored and is not run.

It is important to note that replay will only attempt to run one skipped job execution. If you have a job with a repeating schedule and multiple job executions are skipped, replay will only attempt to run the first skipped job execution; all others are ignored.

For more information about pausing jobs, see Chapter 5.

Job Retry

If a job execution fails, job retry allows that job execution to be attempted again after a specified period of time. For example, if the job execution at midnight on Monday failed due to a power outage, that job execution would be attempted once at 1:00 a.m. If the job execution failed again, it would be ignored, and another attempt would not be made until the next scheduled run time (midnight on Tuesday).

For more information about job retry, see Section 3.2.

Execution Threshold

Execution threshold is essentially a time limit for a job to be run; if the job is not run within a specified period of time, then it is ignored and another attempt to run it is not made until the next scheduled run time. For example, a job scheduled to run nightly at midnight has a 6 hour execution threshold. If the job is not started by 6:00 a.m. on any day, then it is ignored and no attempt will be made to run the job again until midnight that night.

For more information about execution threshold, see Section 3.2.

Blackout Window

A blackout window is a period of time in which all job executions are suppressed. Any job execution that is scheduled to take place between 6:00 a.m. and midnight, for example (either directly scheduled or indirectly through a retry or replay), would be suppressed until the blackout window ends.

For more information about blackout windows, see Chapter 4.

B.2 Job Precedence

The combination of job semantics (for example, job retry or blackout windows) and associated operations (for example, pause and resume) requires precedence to ensure the overall correctness of Job Scheduler and resolve possible conflicts.

For example, consider the following scenarios:

A job execution is resumed with replay during the time in which a blackout window is in effect. Does the job run?
A job execution fails and is retried. Does execution threshold apply to the retry too?
A job execution is paused and resumed with replay. Does execution threshold apply to the replay too?

Table B-1 specifies the precedence of these operations.

Table B-1 Precedence of Job Scheduler Operations

Precedence	Attribute/Operation	Discussion
1 (highest)	Blackout windows	All job executions are suppressed when a blackout window is active.
2	Job resume with replay	When a job execution is resumed with the replay parameter set to true, the job execution will run regardless of lower precedence attributes or operations.
3	Job retry	When a job execution fails, retry takes precedence over execution threshold or a (repeating) schedule end date. The same holds true if the job execution is paused after it is started, but before the retry period.
4	Job execution threshold	Execution threshold pertains to the initial running of the job execution only and not a retry (as a result of a failed attempt) or replay (as a result of resume).
5	Job pause	When a job execution is paused, execution may be postponed until the job is resumed. Both retry and replay take precedence.
6 (lowest)	Schedule end date	The job execution runs when not paused and falls within the execution threshold (if specified).