6 Canceling Jobs

This chapter describes the meaning of canceling a job and also describes how to cancel a job. The following topics are covered:

• What Does it Mean to Cancel a Job?

• Canceling a Job

• Frequently Asked Questions

6.1 What Does it Mean to Cancel a Job?

Canceling a job is the only way to stop a job execution while it is running. It is important to note that while canceling a job stops a job execution that is currently running, it does not prevent that job from being executed in the future. To eliminate all traces of a job from the system, you must remove the job. For more information about removing jobs, see Section 2.3.

Once a job is canceled, it is possible to run the job again by using retry. For more information about retry, see Section 3.2.

6.2 Canceling a Job

To cancel a job, the job must use the oracle.ias.scheduler.Cancellable interface, respond to the cancellation request, and then create the necessary exception, JobCancelledException, to designate the job as canceled.

Any Java job class submitted to Job Scheduler can provide an implementation of the oracle.ias.scheduler.Cancellable interface. Every time a job is canceled (by invoking the Job Scheduler cancel() method), it causes the implementing class's cancel() method to be invoked on all the job's instances.

For more information about the oracle.ias.scheduler.Cancellable interface or cancel() method, see Oracle Containers for J2EE Job Scheduler API Reference.

Example 6-1 shows how to cancel a job with the oracle.ias.scheduler.Cancellable interface.

Example 6-1 Backing Up Data on a Regular Basis with an Option to Cancel

During testing of the application outlined earlier in Example 2-1, it becomes apparent that the job execution may run for long periods of time. Therefore, there may be need to cancel the job execution when it is running.

The following code example shows the modified implementation that provides both oracle.ias.scheduler.Executable and oracle.ias.scheduler.Cancellable interfaces:

import java.io.File;
import java.io.IOException;
import oracle.ias.scheduler.Job;
import oracle.ias.scheduler.Executable;
import oracle.ias.scheduler.Cancellable;
import oracle.ias.scheduler.JobContext;
import oracle.ias.scheduler.JobCancelledException;
import oracle.ias.scheduler.JobExecutionException;


public class CancellableBackupJob implements Executable, Cancellable {

    boolean m_cancelled = false;


    public void cancel() {
        m_cancelled = true;
}


    public void execute(JobContext context) throws
        JobExecutionException, JobCancelledException {

        // retrieve the source and destination directories
        Job job = context.getJob();
        String source = job.getProperties().getProperty("SourceDirectory");
        String destination =            job.getProperties().getProperty("DestinationDirectory");

        // get the list of files to copy
        File directory = new File(source);
        File[] files = directory.listFiles();

        // copy the files
        Runtime runtime = Runtime.getRuntime();
        Process process;
        for (int x = 0; x < files.length; x++) {

            // cancelled?
            if (m_cancelled) {
                throw new JobCancelledException();
            }

            try {
                process = runtime.exec("/bin/cp " + files[x].toString() +
                                       " " + destination);
                process.waitFor();
            } catch(IOException e) {               
                throw new RuntimeException("copy failed: "+files[x],e);
            } catch(InterruptedException e) {
                throw new RuntimeException("copy failed: "+files[x],e);
            }
        }
    }
}

At a minimum, canceling a job means the following:

• The implementation must use the oracle.ias.scheduler.Cancellable interface.

• For the job execution to be canceled, you must invoke the cancel() method, which causes the oracle.ias.scheduler.JobCancelledException exception that will stop the job execution.

• It may not always be possible to immediately invoke the cancel() method; take this into account when you program.

6.3 Frequently Asked Questions

Is there a way to re-execute a job that has been canceled?

No. There is no mechanism to retry an execution that has been canceled. Only failed job executions can be retried.For more information, see Section 3.2.