org.quartz.jobs.InterruptableJob Maven / Gradle / Ivy
/*
* Copyright 2001-2009 Terracotta, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy
* of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
package org.quartz.jobs;
import org.quartz.core.Scheduler;
import org.quartz.exceptions.UnableToInterruptJobException;
/**
* The interface to be implemented by {@link Job}s that provide a mechanism for having their execution interrupted. It is NOT a
* requirement for jobs to implement this interface - in fact, for most people, none of their jobs will.
*
* Interrupting a Job is very analogous in concept and challenge to normal interruption of a Thread in Java.
*
* The means of actually interrupting the Job must be implemented within the Job itself (the interrupt() method of this
* interface is simply a means for the scheduler to inform the Job that a request has been made for it to be interrupted). The mechanism
* that your jobs use to interrupt themselves might vary between implementations. However the principle idea in any implementation should be to have
* the body of the job's execute(..) periodically check some flag to see if an interruption has been requested, and if the flag is set,
* somehow abort the performance of the rest of the job's work. An example of interrupting a job can be found in the java source for the class
* org.quartz.examples.DumbInterruptableJob. It is legal to use some combination of wait() and notify()
* synchronization within interrupt() and execute(..) in order to have the interrupt() method block until the
* execute(..) signals that it has noticed the set flag.
*
*
* If the Job performs some form of blocking I/O or similar functions, you may want to consider having the Job.execute(..) method store a
* reference to the calling Thread as a member variable. Then the Implementation of this interfaces interrupt() method can
* call interrupt() on that Thread. Before attempting this, make sure that you fully understand what
* java.lang.Thread.interrupt() does and doesn't do. Also make sure that you clear the Job's member reference to the Thread when the
* execute(..) method exits (preferably in a finally block.
*
*
* See Example 7 (org.quartz.examples.example7.DumbInterruptableJob) for a simple implementation demonstration.
*
*
* @see Job
* @see StatefulJob
* @see Scheduler#interrupt(JobKey)
* @author James House
*/
public interface InterruptableJob extends Job {
/*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Interface.
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/**
*
* Called by the {@link Scheduler} when a user interrupts the Job.
*
*
* @throws UnableToInterruptJobException if there is an exception while interrupting the job.
*/
void interrupt() throws UnableToInterruptJobException;
}