7 Oracle Application Server Containers for J2EE Events and Listeners

This chapter describes the Job Scheduler event listener framework. The following topics are covered:

• Events and Event Listeners

• Implementing and Binding a Event Listener

• Best Practices for Implementing and Binding Event Listeners

• Frequently Asked Questions About Job Listeners

7.1 Events and Event Listeners

An event represents a change in a job's state; each change in a job's state is represented by a corresponding event. An application can be programmed to react to these events using an event listener. An event listener can be bound to one or more jobs at any time during the life cycle of a job.

The Job Scheduler uses numerous events to represent job state changes. These events are listed in Table 7-1.

Table 7-1 Job Scheduler Events

Event	Description
oracle.ias.scheduler.event.JobBlackoutEvent	Job was suppressed due to a blackout window.
oracle.ias.scheduler.event.JobCompletedEvent	Job scheduled end date passed.
oracle.ias.scheduler.event.JobCreatedEvent	Job was created.
oracle.ias.scheduler.event.JobExecutionCancelledEvent	Job was canceled.
oracle.ias.scheduler.event.JobExecutionFailedEvent	Job failed.
oracle.ias.scheduler.event.JobExecutionPausedEvent	Job was suppressed because the job is currently paused.
oracle.ias.scheduler.event.JobExecutionSucceededEvent	Job successful.
oracle.ias.scheduler.event.JobExecutionThresholdExceededEvent	Job was suppressed because the execution threshold was exceeded.
oracle.ias.scheduler.event.JobPausedEvent	Job was paused.
oracle.ias.scheduler.event.JobRemovedEvent	Job was removed.
oracle.ias.scheduler.event.JobResumedEvent	Previously paused job was resumed.

7.2 Implementing and Binding a Event Listener

To receive events, an event listener is required. An event listener must use the oracle.ias.scheduler.event.EventListener interface. This interface is defined as follows:

public interface EventListener extends java.util.EventListener {
    public void dispatch(SchedulerEvent event) throws Exception;
    public Class[] wants();
}

The wants() method is used to specify the events for which this listener is interested, and returns the associated class object for those specified events. After the listener is implemented, the dispatch() method is invoked every time one of the desired events occurs.

For more information about the oracle.ias.scheduler.event.EventListener interface and its methods, see Oracle Containers for J2EE Job Scheduler API Reference.

Example 7-1 shows how to implement an event listener that is interested in the JobExecutionFailedEvent and JobExecutionSucceededEvent events.

Example 7-1 Job Listener Implementation

import oracle.ias.scheduler.event.*;
 
public class TestListener implements EventListener {
 
    public void dispatch(SchedulerEvent event) {
        System.out.println("Got event, "+event.getClass().getName());
    }
 
    public Class[] wants() {
        return new Class[] {
            oracle.ias.scheduler.event.JobExecutionFailedEvent.class,
            oracle.ias.scheduler.event.JobExecutionSucceeded.class
        };
    }
}

Example 7-2 shows how to bind the TestListener listener created in Example 7-1.

Example 7-2 Binding a Listener to a Job

JobHandle handle = scheduler.add(...);
 
// bind the listener to the job
scheduler.addListener(handle,TestListener.class);

7.3 Best Practices for Implementing and Binding Event Listeners

When implementing and binding job listeners, keep the following in mind:

• Keep job listener processing to a minimum. Events are processed serially by job listeners and lengthy processing should be avoided. If lengthy processing cannot be avoided, consider serializing the event for later processing.

7.4 Frequently Asked Questions About Job Listeners

Can I use the same job listener for every job?

Yes. Use the event's getHandle() method to determine which event is associated with which job.

If I use the same job listener for every job, how many instances of the job listener will there be?

There will be one job listener instance per job.

Is the job listener dispatch( ) method reentrant (can this method be called while it is already in use)?

Yes. Use appropriate measures when modifying job listener member variables (for example, using locks to avoid resource conflicts).

Is the job listener instance state persistent across container restarts?

No. The job listener instance state is not persistent.