01: /*
02: * Copyright 2004-2005 OpenSymphony
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
05: * use this file except in compliance with the License. You may obtain a copy
06: * of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13: * License for the specific language governing permissions and limitations
14: * under the License.
15: *
16: */
17:
18: /*
19: * Previously Copyright (c) 2001-2004 James House
20: */
21: package org.quartz;
22:
23: /**
24: * <p>
25: * The interface to be implemented by <code>{@link Job}s</code> that provide a
26: * mechanism for having their execution interrupted. It is NOT a requirment
27: * for jobs to implement this interface - in fact, for most people, none of
28: * their jobs will.
29: * </p>
30: *
31: * <p>
32: * The means of actually interrupting the Job must be implemented within the
33: * <code>Job</code> itself (the <code>interrupt()</code> method of this
34: * interface is simply a means for the scheduler to inform the <code>Job</code>
35: * that a request has been made for it to be interrupted). The mechanism that
36: * your jobs use to interrupt themselves might vary between implementations.
37: * However the principle idea in any implementation should be to have the
38: * body of the job's <code>execute(..)</code> periodically check some flag to
39: * see if an interruption has been requested, and if the flag is set, somehow
40: * abort the performance of the rest of the job's work. An example of
41: * interrupting a job can be found in the java source for the class
42: * <code>org.quartz.examples.DumbInterruptableJob</code>. It is legal to use
43: * some combination of <code>wait()</code> and <code>notify()</code>
44: * synchronization within <code>interrupt()</code> and <code>execute(..)</code>
45: * in order to have the <code>interrupt()</code> method block until the
46: * <code>execute(..)</code> signals that it has noticed the set flag.
47: * </p>
48: *
49: * <p>
50: * If the Job performs some form of blocking I/O or similar functions, you may
51: * want to consider having the <code>Job.execute(..)</code> method store a
52: * reference to the calling <code>Thread</code> as a member variable. Then the
53: * impplementation of this interfaces <code>interrupt()</code> method can call
54: * <code>interrupt()</code> on that Thread. Before attempting this, make
55: * sure that you fully understand what <code>java.lang.Thread.interrupt()</code>
56: * does and doesn't do. Also make sure that you clear the Job's member
57: * reference to the Thread when the execute(..) method exits (preferrably in a
58: * <code>finally</code> block.
59: * </p>
60: *
61: * <p>
62: * See Example 7 (org.quartz.examples.example7.DumbInterruptableJob) for a simple
63: * implementation demonstration.
64: * </p>
65: * @see Job
66: * @see StatefulJob
67: * @see Scheduler#interrupt(String, String)
68: *
69: * @author James House
70: */
71: public interface InterruptableJob extends Job {
72:
73: /*
74: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75: *
76: * Interface.
77: *
78: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79: */
80:
81: /**
82: * <p>
83: * Called by the <code>{@link Scheduler}</code> when a user
84: * interrupts the <code>Job</code>.
85: * </p>
86: *
87: * @throws UnableToInterruptJobException
88: * if there is an exception while interrupting the job.
89: */
90: void interrupt() throws UnableToInterruptJobException;
91: }
|