io.logspace.agent.shaded.quartz.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 io.logspace.agent.shaded.quartz;
/**
* 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
* io.logspace.agent.shaded.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 (io.logspace.agent.shaded.quartz.examples.example7.DumbInterruptableJob) for a simple
* implementation demonstration.
*
* @see Job
* @see StatefulJob
* @see Scheduler#interrupt(JobKey)
* @see Scheduler#interrupt(String)
*
* @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;
}