Java > Open Source Codes > org > quartz > impl > jdbcjobstore > DriverDelegate


1 /*
2  * Copyright 2004-2005 OpenSymphony
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy
6  * of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
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.impl.jdbcjobstore;
22
23 import java.io.IOException ;
24 import java.sql.Connection ;
25 import java.sql.SQLException ;
26 import java.util.List ;
27 import java.util.Set ;
28
29 import org.quartz.Calendar;
30 import org.quartz.CronTrigger;
31 import org.quartz.JobDataMap;
32 import org.quartz.JobDetail;
33 import org.quartz.SimpleTrigger;
34 import org.quartz.Trigger;
35 import org.quartz.spi.ClassLoadHelper;
36 import org.quartz.utils.Key;
37 import org.quartz.utils.TriggerStatus;
38
39 /**
40  * <p>
41  * This is the base interface for all driver delegate classes.
42  * </p>
43  *
44  * <p>
45  * This interface is very similar to the <code>{@link
46  * org.quartz.spi.JobStore}</code>
47  * interface except each method has an additional <code>{@link java.sql.Connection}</code>
48  * parameter.
49  * </p>
50  *
51  * <p>
52  * Unless a database driver has some <strong>extremely-DB-specific</strong>
53  * requirements, any DriverDelegate implementation classes should extend the
54  * <code>{@link org.quartz.impl.jdbcjobstore.StdJDBCDelegate}</code> class.
55  * </p>
56  *
57  * @author <a HREF="mailto:jeff@binaryfeed.org">Jeffrey Wescott</a>
58  * @author James House
59  */
60 interface DriverDelegate {
61
62     /*
63      * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64      *
65      * Interface.
66      *
67      * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68      */
69
70     //---------------------------------------------------------------------------
71 // startup / recovery
72 //---------------------------------------------------------------------------
73 /**
74      * <p>
75      * Update all triggers having one of the two given states, to the given new
76      * state.
77      * </p>
78      *
79      * @param conn
80      * the DB Connection
81      * @param newState
82      * the new state for the triggers
83      * @param oldState1
84      * the first old state to update
85      * @param oldState2
86      * the second old state to update
87      * @return number of rows updated
88      */
89     int updateTriggerStatesFromOtherStates(Connection conn,
90         String newState, String oldState1, String oldState2)
91         throws SQLException ;
92
93     /**
94      * <p>
95      * Get the names of all of the triggers that have misfired - according to
96      * the given timestamp.
97      * </p>
98      *
99      * @param conn
100      * the DB Connection
101      * @return an array of <code>{@link
102      * org.quartz.utils.Key}</code> objects
103      */
104     Key[] selectMisfiredTriggers(Connection conn, long ts)
105         throws SQLException ;
106
107     /**
108      * <p>
109      * Get the names of all of the triggers in the given state that have
110      * misfired - according to the given timestamp.
111      * </p>
112      *
113      * @param conn
114      * the DB Connection
115      * @return an array of <code>{@link
116      * org.quartz.utils.Key}</code> objects
117      */
118     Key[] selectMisfiredTriggersInState(Connection conn, String state,
119         long ts) throws SQLException ;
120     
121     /**
122      * <p>
123      * Get the names of all of the triggers in the given states that have
124      * misfired - according to the given timestamp. No more than count will
125      * be returned.
126      * </p>
127      *
128      * @param conn the DB Connection
129      * @param count the most misfired triggers to return, negative for all
130      * @param resultList Output parameter. A List of
131      * <code>{@link org.quartz.utils.Key}</code> objects. Must not be null.
132      *
133      * @return Whether there are more misfired triggers left to find beyond
134      * the given count.
135      */
136     boolean selectMisfiredTriggersInStates(Connection conn, String state1, String state2,
137         long ts, int count, List resultList) throws SQLException ;
138     
139     /**
140      * <p>
141      * Get the number of triggers in the given states that have
142      * misfired - according to the given timestamp.
143      * </p>
144      *
145      * @param conn the DB Connection
146      */
147     int countMisfiredTriggersInStates(
148         Connection conn, String state1, String state2, long ts) throws SQLException ;
149
150     /**
151      * <p>
152      * Get the names of all of the triggers in the given group and state that
153      * have misfired - according to the given timestamp.
154      * </p>
155      *
156      * @param conn
157      * the DB Connection
158      * @return an array of <code>{@link
159      * org.quartz.utils.Key}</code> objects
160      */
161     Key[] selectMisfiredTriggersInGroupInState(Connection conn,
162         String groupName, String state, long ts) throws SQLException ;
163     
164
165     /**
166      * <p>
167      * Select all of the triggers for jobs that are requesting recovery. The
168      * returned trigger objects will have unique "recoverXXX" trigger names and
169      * will be in the <code>{@link
170      * org.quartz.Scheduler}.DEFAULT_RECOVERY_GROUP</code>
171      * trigger group.
172      * </p>
173      *
174      * <p>
175      * In order to preserve the ordering of the triggers, the fire time will be
176      * set from the <code>COL_FIRED_TIME</code> column in the <code>TABLE_FIRED_TRIGGERS</code>
177      * table. The caller is responsible for calling <code>computeFirstFireTime</code>
178      * on each returned trigger. It is also up to the caller to insert the
179      * returned triggers to ensure that they are fired.
180      * </p>
181      *
182      * @param conn
183      * the DB Connection
184      * @return an array of <code>{@link org.quartz.Trigger}</code> objects
185      */
186     Trigger[] selectTriggersForRecoveringJobs(Connection conn)
187         throws SQLException , IOException , ClassNotFoundException ;
188
189     /**
190      * <p>
191      * Delete all fired triggers.
192      * </p>
193      *
194      * @param conn
195      * the DB Connection
196      * @return the number of rows deleted
197      */
198     int deleteFiredTriggers(Connection conn) throws SQLException ;
199
200     /**
201      * <p>
202      * Delete all fired triggers of the given instance.
203      * </p>
204      *
205      * @param conn
206      * the DB Connection
207      * @return the number of rows deleted
208      */
209     int deleteFiredTriggers(Connection conn, String instanceId)
210         throws SQLException ;
211
212     /**
213      * <p>
214      * Delete all volatile fired triggers.
215      * </p>
216      *
217      * @param conn
218      * the DB Connection
219      * @return the number of rows deleted
220      */
221     int deleteVolatileFiredTriggers(Connection conn) throws SQLException ;
222
223     /**
224      * <p>
225      * Get the names of all of the triggers that are volatile.
226      * </p>
227      *
228      * @param conn
229      * the DB Connection
230      * @return an array of <code>{@link
231      * org.quartz.utils.Key}</code> objects
232      */
233     Key[] selectVolatileTriggers(Connection conn) throws SQLException ;
234
235     /**
236      * <p>
237      * Get the names of all of the jobs that are volatile.
238      * </p>
239      *
240      * @param conn
241      * the DB Connection
242      * @return an array of <code>{@link
243      * org.quartz.utils.Key}</code> objects
244      */
245     Key[] selectVolatileJobs(Connection conn) throws SQLException ;
246
247     //---------------------------------------------------------------------------
248 // jobs
249 //---------------------------------------------------------------------------
250
251     /**
252      * <p>
253      * Insert the job detail record.
254      * </p>
255      *
256      * @param conn
257      * the DB Connection
258      * @param job
259      * the job to insert
260      * @return number of rows inserted
261      * @throws IOException
262      * if there were problems serializing the JobDataMap
263      */
264     int insertJobDetail(Connection conn, JobDetail job)
265         throws IOException , SQLException ;
266
267     /**
268      * <p>
269      * Update the job detail record.
270      * </p>
271      *
272      * @param conn
273      * the DB Connection
274      * @param job
275      * the job to update
276      * @return number of rows updated
277      * @throws IOException
278      * if there were problems serializing the JobDataMap
279      */
280     int updateJobDetail(Connection conn, JobDetail job)
281         throws IOException , SQLException ;
282
283     /**
284      * <p>
285      * Get the names of all of the triggers associated with the given job.
286      * </p>
287      *
288      * @param conn
289      * the DB Connection
290      * @param jobName
291      * the job name
292      * @param groupName
293      * the job group
294      * @return an array of <code>{@link
295      * org.quartz.utils.Key}</code> objects
296      */
297     Key[] selectTriggerNamesForJob(Connection conn, String jobName,
298         String groupName) throws SQLException ;
299
300     /**
301      * <p>
302      * Delete all job listeners for the given job.
303      * </p>
304      *
305      * @param conn
306      * the DB Connection
307      * @param jobName
308      * the name of the job
309      * @param groupName
310      * the group containing the job
311      * @return the number of rows deleted
312      */
313     int deleteJobListeners(Connection conn, String jobName,
314         String groupName) throws SQLException ;
315
316     /**
317      * <p>
318      * Delete the job detail record for the given job.
319      * </p>
320      *
321      * @param conn
322      * the DB Connection
323      * @param jobName
324      * the name of the job
325      * @param groupName
326      * the group containing the job
327      * @return the number of rows deleted
328      */
329     int deleteJobDetail(Connection conn, String jobName, String groupName)
330         throws SQLException ;
331
332     /**
333      * <p>
334      * Check whether or not the given job is stateful.
335      * </p>
336      *
337      * @param conn
338      * the DB Connection
339      * @param jobName
340      * the name of the job
341      * @param groupName
342      * the group containing the job
343      * @return true if the job exists and is stateful, false otherwise
344      */
345     boolean isJobStateful(Connection conn, String jobName,
346         String groupName) throws SQLException ;
347
348     /**
349      * <p>
350      * Check whether or not the given job exists.
351      * </p>
352      *
353      * @param conn
354      * the DB Connection
355      * @param jobName
356      * the name of the job
357      * @param groupName
358      * the group containing the job
359      * @return true if the job exists, false otherwise
360      */
361     boolean jobExists(Connection conn, String jobName, String groupName)
362         throws SQLException ;
363
364     /**
365      * <p>
366      * Update the job data map for the given job.
367      * </p>
368      *
369      * @param conn
370      * the DB Connection
371      * @param job
372      * the job to update
373      * @return the number of rows updated
374      * @throws IOException
375      * if there were problems serializing the JobDataMap
376      */
377     int updateJobData(Connection conn, JobDetail job)
378         throws IOException , SQLException ;
379
380     /**
381      * <p>
382      * Associate a listener with a job.
383      * </p>
384      *
385      * @param conn
386      * the DB Connection
387      * @param job
388      * the job to associate with the listener
389      * @param listener
390      * the listener to insert
391      * @return the number of rows inserted
392      */
393     int insertJobListener(Connection conn, JobDetail job, String listener)
394         throws SQLException ;
395
396     /**
397      * <p>
398      * Get all of the listeners for a given job.
399      * </p>
400      *
401      * @param conn
402      * the DB Connection
403      * @param jobName
404      * the job name whose listeners are wanted
405      * @param groupName
406      * the group containing the job
407      * @return array of <code>String</code> listener names
408      */
409     String [] selectJobListeners(Connection conn, String jobName,
410         String groupName) throws SQLException ;
411
412     /**
413      * <p>
414      * Select the JobDetail object for a given job name / group name.
415      * </p>
416      *
417      * @param conn
418      * the DB Connection
419      * @param jobName
420      * the job name whose listeners are wanted
421      * @param groupName
422      * the group containing the job
423      * @return the populated JobDetail object
424      * @throws ClassNotFoundException
425      * if a class found during deserialization cannot be found or if
426      * the job class could not be found
427      * @throws IOException
428      * if deserialization causes an error
429      */
430     JobDetail selectJobDetail(Connection conn, String jobName,
431         String groupName, ClassLoadHelper loadHelper)
432         throws ClassNotFoundException , IOException , SQLException ;
433
434     /**
435      * <p>
436      * Select the total number of jobs stored.
437      * </p>
438      *
439      * @param conn
440      * the DB Connection
441      * @return the total number of jobs stored
442      */
443     int selectNumJobs(Connection conn) throws SQLException ;
444
445     /**
446      * <p>
447      * Select all of the job group names that are stored.
448      * </p>
449      *
450      * @param conn
451      * the DB Connection
452      * @return an array of <code>String</code> group names
453      */
454     String [] selectJobGroups(Connection conn) throws SQLException ;
455
456     /**
457      * <p>
458      * Select all of the jobs contained in a given group.
459      * </p>
460      *
461      * @param conn
462      * the DB Connection
463      * @param groupName
464      * the group containing the jobs
465      * @return an array of <code>String</code> job names
466      */
467     String [] selectJobsInGroup(Connection conn, String groupName)
468         throws SQLException ;
469
470     //---------------------------------------------------------------------------
471 // triggers
472 //---------------------------------------------------------------------------
473
474     /**
475      * <p>
476      * Insert the base trigger data.
477      * </p>
478      *
479      * @param conn
480      * the DB Connection
481      * @param trigger
482      * the trigger to insert
483      * @param state
484      * the state that the trigger should be stored in
485      * @return the number of rows inserted
486      */
487     int insertTrigger(Connection conn, Trigger trigger, String state,
488         JobDetail jobDetail) throws SQLException , IOException ;
489
490     /**
491      * <p>
492      * Insert the simple trigger data.
493      * </p>
494      *
495      * @param conn
496      * the DB Connection
497      * @param trigger
498      * the trigger to insert
499      * @return the number of rows inserted
500      */
501     int insertSimpleTrigger(Connection conn, SimpleTrigger trigger)
502         throws SQLException ;
503
504     /**
505      * <p>
506      * Insert the blob trigger data.
507      * </p>
508      *
509      * @param conn
510      * the DB Connection
511      * @param trigger
512      * the trigger to insert
513      * @return the number of rows inserted
514      */
515     int insertBlobTrigger(Connection conn, Trigger trigger)
516         throws SQLException , IOException ;
517
518     /**
519      * <p>
520      * Insert the cron trigger data.
521      * </p>
522      *
523      * @param conn
524      * the DB Connection
525      * @param trigger
526      * the trigger to insert
527      * @return the number of rows inserted
528      */
529     int insertCronTrigger(Connection conn, CronTrigger trigger)
530         throws SQLException ;
531
532     /**
533      * <p>
534      * Update the base trigger data.
535      * </p>
536      *
537      * @param conn
538      * the DB Connection
539      * @param trigger
540      * the trigger to insert
541      * @param state
542      * the state that the trigger should be stored in
543      * @return the number of rows updated
544      */
545     int updateTrigger(Connection conn, Trigger trigger, String state,
546         JobDetail jobDetail) throws SQLException , IOException ;
547
548     /**
549      * <p>
550      * Update the simple trigger data.
551      * </p>
552      *
553      * @param conn
554      * the DB Connection
555      * @param trigger
556      * the trigger to insert
557      * @return the number of rows updated
558      */
559     int updateSimpleTrigger(Connection conn, SimpleTrigger trigger)
560         throws SQLException ;
561
562     /**
563      * <p>
564      * Update the cron trigger data.
565      * </p>
566      *
567      * @param conn
568      * the DB Connection
569      * @param trigger
570      * the trigger to insert
571      * @return the number of rows updated
572      */
573     int updateCronTrigger(Connection conn, CronTrigger trigger)
574         throws SQLException ;
575
576     /**
577      * <p>
578      * Update the blob trigger data.
579      * </p>
580      *
581      * @param conn
582      * the DB Connection
583      * @param trigger
584      * the trigger to insert
585      * @return the number of rows updated
586      */
587     int updateBlobTrigger(Connection conn, Trigger trigger)
588         throws SQLException , IOException ;
589
590     /**
591      * <p>
592      * Check whether or not a trigger exists.
593      * </p>
594      *
595      * @param conn
596      * the DB Connection
597      * @param triggerName
598      * the name of the trigger
599      * @param groupName
600      * the group containing the trigger
601      * @return the number of rows updated
602      */
603     boolean triggerExists(Connection conn, String triggerName,
604         String groupName) throws SQLException ;
605
606     /**
607      * <p>
608      * Update the state for a given trigger.
609      * </p>
610      *
611      * @param conn
612      * the DB Connection
613      * @param triggerName
614      * the name of the trigger
615      * @param groupName
616      * the group containing the trigger
617      * @param state
618      * the new state for the trigger
619      * @return the number of rows updated
620      */
621     int updateTriggerState(Connection conn, String triggerName,
622         String groupName, String state) throws SQLException ;
623
624     /**
625      * <p>
626      * Update the given trigger to the given new state, if it is in the given
627      * old state.
628      * </p>
629      *
630      * @param conn
631      * the DB connection
632      * @param triggerName
633      * the name of the trigger
634      * @param groupName
635      * the group containing the trigger
636      * @param newState
637      * the new state for the trigger
638      * @param oldState
639      * the old state the trigger must be in
640      * @return int the number of rows updated
641      * @throws SQLException
642      */
643     int updateTriggerStateFromOtherState(Connection conn,
644         String triggerName, String groupName, String newState,
645         String oldState) throws SQLException ;
646
647     /**
648      * <p>
649      * Update the given trigger to the given new state, if it is one of the
650      * given old states.
651      * </p>
652      *
653      * @param conn
654      * the DB connection
655      * @param triggerName
656      * the name of the trigger
657      * @param groupName
658      * the group containing the trigger
659      * @param newState
660      * the new state for the trigger
661      * @param oldState1
662      * one of the old state the trigger must be in
663      * @param oldState2
664      * one of the old state the trigger must be in
665      * @param oldState3
666      * one of the old state the trigger must be in
667      * @return int the number of rows updated
668      * @throws SQLException
669      */
670     int updateTriggerStateFromOtherStates(Connection conn,
671         String triggerName, String groupName, String newState,
672         String oldState1, String oldState2, String oldState3)
673         throws SQLException ;
674
675     /**
676      * <p>
677      * Update the all triggers to the given new state, if they are in one of
678      * the given old states AND its next fire time is before the given time.
679      * </p>
680      *
681      * @param conn
682      * the DB connection
683      * @param newState
684      * the new state for the trigger
685      * @param oldState1
686      * one of the old state the trigger must be in
687      * @param oldState2
688      * one of the old state the trigger must be in
689      * @param time
690      * the time before which the trigger's next fire time must be
691      * @return int the number of rows updated
692      * @throws SQLException
693      */
694     int updateTriggerStateFromOtherStatesBeforeTime(Connection conn,
695         String newState, String oldState1, String oldState2, long time)
696         throws SQLException ;
697
698     /**
699      * <p>
700      * Update all triggers in the given group to the given new state, if they
701      * are in one of the given old states.
702      * </p>
703      *
704      * @param conn
705      * the DB connection
706      * @param groupName
707      * the group containing the trigger
708      * @param newState
709      * the new state for the trigger
710      * @param oldState1
711      * one of the old state the trigger must be in
712      * @param oldState2
713      * one of the old state the trigger must be in
714      * @param oldState3
715      * one of the old state the trigger must be in
716      * @return int the number of rows updated
717      * @throws SQLException
718      */
719     int updateTriggerGroupStateFromOtherStates(Connection conn,
720         String groupName, String newState, String oldState1,
721         String oldState2, String oldState3) throws SQLException ;
722
723     /**
724      * <p>
725      * Update all of the triggers of the given group to the given new state, if
726      * they are in the given old state.
727      * </p>
728      *
729      * @param conn
730      * the DB connection
731      * @param groupName
732      * the group containing the triggers
733      * @param newState
734      * the new state for the trigger group
735      * @param oldState
736      * the old state the triggers must be in
737      * @return int the number of rows updated
738      * @throws SQLException
739      */
740     int updateTriggerGroupStateFromOtherState(Connection conn,
741         String groupName, String newState, String oldState)
742         throws SQLException ;
743
744     /**
745      * <p>
746      * Update the states of all triggers associated with the given job.
747      * </p>
748      *
749      * @param conn
750      * the DB Connection
751      * @param jobName
752      * the name of the job
753      * @param groupName
754      * the group containing the job
755      * @param state
756      * the new state for the triggers
757      * @return the number of rows updated
758      */
759     int updateTriggerStatesForJob(Connection conn, String jobName,
760         String groupName, String state) throws SQLException ;
761
762     /**
763      * <p>
764      * Update the states of any triggers associated with the given job, that
765      * are the given current state.
766      * </p>
767      *
768      * @param conn
769      * the DB Connection
770      * @param jobName
771      * the name of the job
772      * @param groupName
773      * the group containing the job
774      * @param state
775      * the new state for the triggers
776      * @param oldState
777      * the old state of the triggers
778      * @return the number of rows updated
779      */
780     int updateTriggerStatesForJobFromOtherState(Connection conn,
781         String jobName, String groupName, String state, String oldState)
782         throws SQLException ;
783
784     /**
785      * <p>
786      * Delete all of the listeners associated with a given trigger.
787      * </p>
788      *
789      * @param conn
790      * the DB Connection
791      * @param triggerName
792      * the name of the trigger whose listeners will be deleted
793      * @param groupName
794      * the name of the group containing the trigger
795      * @return the number of rows deleted
796      */
797     int deleteTriggerListeners(Connection conn, String triggerName,
798         String groupName) throws SQLException ;
799
800     /**
801      * <p>
802      * Associate a listener with the given trigger.
803      * </p>
804      *
805      * @param conn
806      * the DB Connection
807      * @param trigger
808      * the trigger
809      * @param listener
810      * the name of the listener to associate with the trigger
811      * @return the number of rows inserted
812      */
813     int insertTriggerListener(Connection conn, Trigger trigger,
814         String listener) throws SQLException ;
815
816     /**
817      * <p>
818      * Select the listeners associated with a given trigger.
819      * </p>
820      *
821      * @param conn
822      * the DB Connection
823      * @param triggerName
824      * the name of the trigger
825      * @param groupName
826      * the group containing the trigger
827      * @return array of <code>String</code> trigger listener names
828      */
829     String [] selectTriggerListeners(Connection conn, String triggerName,
830         String groupName) throws SQLException ;
831
832     /**
833      * <p>
834      * Delete the simple trigger data for a trigger.
835      * </p>
836      *
837      * @param conn
838      * the DB Connection
839      * @param triggerName
840      * the name of the trigger
841      * @param groupName
842      * the group containing the trigger
843      * @return the number of rows deleted
844      */
845     int deleteSimpleTrigger(Connection conn, String triggerName,
846         String groupName) throws SQLException ;
847
848     /**
849      * <p>
850      * Delete the BLOB trigger data for a trigger.
851      * </p>
852      *
853      * @param conn
854      * the DB Connection
855      * @param triggerName
856      * the name of the trigger
857      * @param groupName
858      * the group containing the trigger
859      * @return the number of rows deleted
860      */
861     int deleteBlobTrigger(Connection conn, String triggerName,
862         String groupName) throws SQLException ;
863
864     /**
865      * <p>
866      * Delete the cron trigger data for a trigger.
867      * </p>
868      *
869      * @param conn
870      * the DB Connection
871      * @param triggerName
872      * the name of the trigger
873      * @param groupName
874      * the group containing the trigger
875      * @return the number of rows deleted
876      */
877     int deleteCronTrigger(Connection conn, String triggerName,
878         String groupName) throws SQLException ;
879
880     /**
881      * <p>
882      * Delete the base trigger data for a trigger.
883      * </p>
884      *
885      * @param conn
886      * the DB Connection
887      * @param triggerName
888      * the name of the trigger
889      * @param groupName
890      * the group containing the trigger
891      * @return the number of rows deleted
892      */
893     int deleteTrigger(Connection conn, String triggerName,
894         String groupName) throws SQLException ;
895
896     /**
897      * <p>
898      * Select the number of triggers associated with a given job.
899      * </p>
900      *
901      * @param conn
902      * the DB Connection
903      * @param jobName
904      * the name of the job
905      * @param groupName
906      * the group containing the job
907      * @return the number of triggers for the given job
908      */
909     int selectNumTriggersForJob(Connection conn, String jobName,
910         String groupName) throws SQLException ;
911
912     /**
913      * <p>
91