|
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 triggers and notifications. The following topics are covered:
This section introduces two concepts: triggers and notifications. Notifications are messages sent from one object to another, in effect notifying the recipient that something happened. The recipient of a notification is called a trigger. A trigger contains certain conditions that are evaluated against one or more notifications that it receives. When a specified condition is met, an associated job is run.
A trigger's conditions are described by a logical expression where the operands are job notification assertions. Notifications can be generated in either of the following ways:
Programatically by the application
As the result of a timer expiration
Likewise, notifications can either be sent to a specific trigger or to a specified set of triggers. On receipt, however, triggers do not generate notifications. By employing the use of triggers, jobs can be enabled to respond to specific application conditions (for example, triggering a job based on revenue exceeding a certain threshold).
The system-supplied oracle.ias.scheduler.Trigger class is used to specify the conditions by which the associated job is run. A condition is expressed as a logical combination of operands. The following logical operators are allowed:
AND (represented as '&&')
OR (represented as '||')
NOT (represented as '!')
Precedence can be specified using parentheses. The following are a few example expressions:
N
Execute when the N notification is received.
N1 || N2
Execute when either notification is received.
N1 && N2
Execute when both notifications are received.
N1 || (N2 && N3)
Execute when either the N1 notification is received or when both N2 and N3 notifications are received.
The operand in a condition is the name associated with the notifications sent using the Job Scheduler's notify() method. For example, to send the DataHasArrived notification to all triggers, the application uses the following code:
Scheduler.notify(new Notification("DataHasArrived"));
Job Scheduler evaluates triggers when a notification is sent. The result of a trigger evaluation is boolean. If the trigger evaluates to true, then the associated job starts. After the trigger fires, it is immediately reset, before the job runs. When the trigger is reset, the record of all previously received notifications by the trigger is erased. A trigger is reset only when the job runs. If the trigger does not fire, the notification is recorded by the trigger for later use.
For example, suppose a trigger has the following condition:
N1 && N2
Assume the trigger receives only notification N1; the trigger evaluates to false, and the notification is recorded. Later, the trigger receives notification N2. Now that both conditions are met, the trigger evaluates to true; the job runs, and the trigger is reset.
Jobs can be associated with a schedule, trigger, or both a schedule and trigger. When a job is associated with a schedule only, an implicit trigger is associated with the job. A trigger of this type provides the following condition:
timeout
When the schedule expires, a timeout notification is sent to the associated trigger for processing. In this case, the trigger fires; the job runs, and the trigger is reset. The timeout notification may also be used in a trigger expression along with other notifications. For example:
timeout || N
Run when the either N notification is received or the schedule expires.
timeout && N
Run when the N notification is received and the schedule expires.
The timeout notification can only be used in cases where the job is associated with both a schedule and a trigger. The timeout notification name is likewise reserved and can not be used or sent by an application to the scheduler. This behavior is consistent with the Notification class. Additionally, the timeout notification must be referenced in the condition expression of the trigger.
If you use the NOT operator in a trigger expression, then be aware of the following:
NOT expressions should include at least two operators. Otherwise, the trigger fires when any other notification is received. For example, the expression !N would cause the trigger to fire whenever any notification except N was received.
NOT expressions should not be used with a schedule that repeats indefinitely. This may result in a permanently hung trigger. Recall that a trigger retains all notifications that were received until the trigger fires. If the trigger receives a notification that satisfies the NOT condition, the trigger will never fire.
To submit a job with a trigger, use the oracle.ias.scheduler.Trigger class. For more information, see Oracle Containers for J2EE Job Scheduler API Reference.
Example 8-1 shows how to create a trigger to run a job when the diskIsFull notification is received.
Example 8-1 Submitting a Job with a Trigger
// set up the trigger, run when 'diskIsFull' notification is received
Trigger trigger = new Trigger("diskIsFull");
// submit the job
scheduler.add("disk is full job",
diskFullJob.class.getName(),
trigger,
null);
To embellish Example 8-1, Example 8-2 shows how to create a trigger to run a job every night at midnight if either the diskIsFull or timeout notifications is received.
Example 8-2 Submitting a Job with a Trigger and a Schedule
// set up the schedule, repeats every night at midnight
RecurSchedule schedule = new RecurSchedule("freq=daily,byhour=0;");
// set up the trigger, run when either 'diskIsFull'
// notification is received or the schedule expires
Trigger trigger = new Trigger("diskIsFull || timeout");
// submit the job
scheduler.add("disk is full job",
DiskFullJob.class.getName(),
schedule,
trigger,
null,
Level.WARN,
0L,
0L);
To send a notification to a job, use the oracle.ias.scheduler.Scheduler.notify() method. For more information, see Oracle Containers for J2EE Job Scheduler API Reference.
Example 8-3 shows how to send the diskIsFull notification to a job.
