JobStore


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.spi;
22  
23  import java.util.Set  ;
24  
25  import org.quartz.Calendar;
26  import org.quartz.JobDetail;
27  import org.quartz.JobPersistenceException;
28  import org.quartz.ObjectAlreadyExistsException;
29  import org.quartz.SchedulerConfigException;
30  import org.quartz.SchedulerException;
31  import org.quartz.Trigger;
32  import org.quartz.core.SchedulingContext;
33  
34  /**
35   * <p>
36   * The interface to be implemented by classes that want to provide a <code>{@link org.quartz.Job}</code>
37   * and <code>{@link org.quartz.Trigger}</code> storage mechanism for the
38   * <code>{@link org.quartz.core.QuartzScheduler}</code>'s use.
39   * </p>
40   * 
41   * <p>
42   * Storage of <code>Job</code> s and <code>Trigger</code> s should be keyed
43   * on the combination of their name and group for uniqueness.
44   * </p>
45   * 
46   * @see org.quartz.core.QuartzScheduler
47   * @see org.quartz.Trigger
48   * @see org.quartz.Job
49   * @see org.quartz.JobDetail
50   * @see org.quartz.JobDataMap
51   * @see org.quartz.Calendar
52   * 
53   * @author James House
54   * @author Eric Mueller
55   */
56  public interface JobStore {
57  
58      /*
59       * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60       * 
61       * Interface.
62       * 
63       * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64       */
65  
66      /**
67       * <p>
68       * Called by the QuartzScheduler before the <code>JobStore</code> is
69       * used, in order to give the it a chance to initialize.
70       * </p>
71       */
72      void initialize(ClassLoadHelper loadHelper,
73              SchedulerSignaler signaler) throws SchedulerConfigException;
74  
75      /**
76       * <p>
77       * Called by the QuartzScheduler to inform the <code>JobStore</code> that
78       * the scheduler has started.
79       * </p>
80       */
81      void schedulerStarted() throws SchedulerException ;
82      
83      /**
84       * <p>
85       * Called by the QuartzScheduler to inform the <code>JobStore</code> that
86       * it should free up all of it's resources because the scheduler is
87       * shutting down.
88       * </p>
89       */
90      void shutdown();
91  
92      boolean supportsPersistence();
93  
94      /////////////////////////////////////////////////////////////////////////////
95      //
96      // Job & Trigger Storage methods
97      //
98      /////////////////////////////////////////////////////////////////////////////
99  
100     /**
101      * <p>
102      * Store the given <code>{@link org.quartz.JobDetail}</code> and <code>{@link org.quartz.Trigger}</code>.
103      * </p>
104      * 
105      * @param newJob
106      *          The <code>JobDetail</code> to be stored.
107      * @param newTrigger
108      *          The <code>Trigger</code> to be stored.
109      * @throws ObjectAlreadyExistsException
110      *           if a <code>Job</code> with the same name/group already
111      *           exists.
112      */
113     void storeJobAndTrigger(SchedulingContext ctxt, JobDetail newJob,
114             Trigger newTrigger) throws ObjectAlreadyExistsException,
115             JobPersistenceException;
116 
117     /**
118      * <p>
119      * Store the given <code>{@link org.quartz.JobDetail}</code>.
120      * </p>
121      * 
122      * @param newJob
123      *          The <code>JobDetail</code> to be stored.
124      * @param replaceExisting
125      *          If <code>true</code>, any <code>Job</code> existing in the
126      *          <code>JobStore</code> with the same name & group should be
127      *          over-written.
128      * @throws ObjectAlreadyExistsException
129      *           if a <code>Job</code> with the same name/group already
130      *           exists, and replaceExisting is set to false.
131      */
132     void storeJob(SchedulingContext ctxt, JobDetail newJob,
133             boolean replaceExisting) throws ObjectAlreadyExistsException,
134             JobPersistenceException;
135 
136     /**
137      * <p>
138      * Remove (delete) the <code>{@link org.quartz.Job}</code> with the given
139      * name, and any <code>{@link org.quartz.Trigger}</code> s that reference
140      * it.
141      * </p>
142      * 
143      * <p>
144      * If removal of the <code>Job</code> results in an empty group, the
145      * group should be removed from the <code>JobStore</code>'s list of
146      * known group names.
147      * </p>
148      * 
149      * @param jobName
150      *          The name of the <code>Job</code> to be removed.
151      * @param groupName
152      *          The group name of the <code>Job</code> to be removed.
153      * @return <code>true</code> if a <code>Job</code> with the given name &
154      *         group was found and removed from the store.
155      */
156     boolean removeJob(SchedulingContext ctxt, String   jobName,
157             String   groupName) throws JobPersistenceException;
158 
159     /**
160      * <p>
161      * Retrieve the <code>{@link org.quartz.JobDetail}</code> for the given
162      * <code>{@link org.quartz.Job}</code>.
163      * </p>
164      * 
165      * @param jobName
166      *          The name of the <code>Job</code> to be retrieved.
167      * @param groupName
168      *          The group name of the <code>Job</code> to be retrieved.
169      * @return The desired <code>Job</code>, or null if there is no match.
170      */
171     JobDetail retrieveJob(SchedulingContext ctxt, String   jobName,
172             String   groupName) throws JobPersistenceException;
173 
174     /**
175      * <p>
176      * Store the given <code>{@link org.quartz.Trigger}</code>.
177      * </p>
178      * 
179      * @param newTrigger
180      *          The <code>Trigger</code> to be stored.
181      * @param replaceExisting
182      *          If <code>true</code>, any <code>Trigger</code> existing in
183      *          the <code>JobStore</code> with the same name & group should
184      *          be over-written.
185      * @throws ObjectAlreadyExistsException
186      *           if a <code>Trigger</code> with the same name/group already
187      *           exists, and replaceExisting is set to false.
188      * 
189      * @see #pauseTriggerGroup(SchedulingContext, String)
190      */
191     void storeTrigger(SchedulingContext ctxt, Trigger newTrigger,
192             boolean replaceExisting) throws ObjectAlreadyExistsException,
193             JobPersistenceException;
194 
195     /**
196      * <p>
197      * Remove (delete) the <code>{@link org.quartz.Trigger}</code> with the
198      * given name.
199      * </p>
200      * 
201      * <p>
202      * If removal of the <code>Trigger</code> results in an empty group, the
203      * group should be removed from the <code>JobStore</code>'s list of
204      * known group names.
205      * </p>
206      * 
207      * <p>
208      * If removal of the <code>Trigger</code> results in an 'orphaned' <code>Job</code>
209      * that is not 'durable', then the <code>Job</code> should be deleted
210      * also.
211      * </p>
212      * 
213      * @param triggerName
214      *          The name of the <code>Trigger</code> to be removed.
215      * @param groupName
216      *          The group name of the <code>Trigger</code> to be removed.
217      * @return <code>true</code> if a <code>Trigger</code> with the given
218      *         name & group was found and removed from the store.
219      */
220     boolean removeTrigger(SchedulingContext ctxt, String   triggerName,
221             String   groupName) throws JobPersistenceException;
222 
223     /**
224      * <p>
225      * Remove (delete) the <code>{@link org.quartz.Trigger}</code> with the
226      * given name, and store the new given one - which must be associated
227      * with the same job.
228      * </p>
229      * 
230      * @param triggerName
231      *          The name of the <code>Trigger</code> to be removed.
232      * @param groupName
233      *          The group name of the <code>Trigger</code> to be removed.
234      * @param newTrigger
235      *          The new <code>Trigger</code> to be stored.
236      * @return <code>true</code> if a <code>Trigger</code> with the given
237      *         name & group was found and removed from the store.
238      */
239     boolean replaceTrigger(SchedulingContext ctxt, String   triggerName,
240             String   groupName, Trigger newTrigger) throws JobPersistenceException;
241 
242     
243     /**
244      * <p>
245      * Retrieve the given <code>{@link org.quartz.Trigger}</code>.
246      * </p>
247      * 
248      * @param triggerName
249      *          The name of the <code>Trigger</code> to be retrieved.
250      * @param groupName
251      *          The group name of the <code>Trigger</code> to be retrieved.
252      * @return The desired <code>Trigger</code>, or null if there is no
253      *         match.
254      */
255     Trigger retrieveTrigger(SchedulingContext ctxt, String   triggerName,
256             String   groupName) throws JobPersistenceException;
257 
258     /**
259      * <p>
260      * Store the given <code>{@link org.quartz.Calendar}</code>.
261      * </p>
262      * 
263      * @param calendar
264      *          The <code>Calendar</code> to be stored.
265      * @param replaceExisting
266      *          If <code>true</code>, any <code>Calendar</code> existing
267      *          in the <code>JobStore</code> with the same name & group
268      *          should be over-written.
269      * @param updateTriggers
270      *          If <code>true</code>, any <code>Trigger</code>s existing
271      *          in the <code>JobStore</code> that reference an existing 
272      *          Calendar with the same name with have their next fire time
273      *          re-computed with the new <code>Calendar</code>.
274      * @throws ObjectAlreadyExistsException
275      *           if a <code>Calendar</code> with the same name already
276      *           exists, and replaceExisting is set to false.
277      */
278     void storeCalendar(SchedulingContext ctxt, String   name,
279             Calendar calendar, boolean replaceExisting, boolean updateTriggers)
280         throws ObjectAlreadyExistsException, JobPersistenceException;
281 
282     /**
283      * <p>
284      * Remove (delete) the <code>{@link org.quartz.Calendar}</code> with the
285      * given name.
286      * </p>
287      * 
288      * <p>
289      * If removal of the <code>Calendar</code> would result in
290      * <code.Trigger</code>s pointing to non-existent calendars, then a
291      * <code>JobPersistenceException</code> will be thrown.</p>
292      *       *
293      * @param calName The name of the <code>Calendar</code> to be removed.
294      * @return <code>true</code> if a <code>Calendar</code> with the given name
295      * was found and removed from the store.
296      */
297     boolean removeCalendar(SchedulingContext ctxt, String   calName)
298         throws JobPersistenceException;
299 
300     /**
301      * <p>
302      * Retrieve the given <code>{@link org.quartz.Trigger}</code>.
303      * </p>
304      * 
305      * @param calName
306      *          The name of the <code>Calendar</code> to be retrieved.
307      * @return The desired <code>Calendar</code>, or null if there is no
308      *         match.
309      */
310     Calendar retrieveCalendar(SchedulingContext ctxt, String   calName)
311         throws JobPersistenceException;
312 
313     /////////////////////////////////////////////////////////////////////////////
314     //
315     // Informational methods
316     //
317     /////////////////////////////////////////////////////////////////////////////
318 
319     /**
320      * <p>
321      * Get the number of <code>{@link org.quartz.Job}</code> s that are
322      * stored in the <code>JobsStore</code>.
323      * </p>
324      */
325     int getNumberOfJobs(SchedulingContext ctxt)
326         throws JobPersistenceException;
327 
328     /**
329      * <p>
330      * Get the number of <code>{@link org.quartz.Trigger}</code> s that are
331      * stored in the <code>JobsStore</code>.
332      * </p>
333      */
334     int getNumberOfTriggers(SchedulingContext ctxt)
335         throws JobPersistenceException;
336 
337     /**
338      * <p>
339      * Get the number of <code>{@link org.quartz.Calendar}</code> s that are
340      * stored in the <code>JobsStore</code>.
341      * </p>
342      */
343     int getNumberOfCalendars(SchedulingContext ctxt)
344         throws JobPersistenceException;
345 
346     /**
347      * <p>
348      * Get the names of all of the <code>{@link org.quartz.Job}</code> s that
349      * have the given group name.
350      * </p>
351      * 
352      * <p>
353      * If there are no jobs in the given group name, the result should be a
354      * zero-length array (not <code>null</code>).
355      * </p>
356      */
357     String  [] getJobNames(SchedulingContext ctxt, String   groupName)
358         throws JobPersistenceException;
359 
360     /**
361      * <p>
362      * Get the names of all of the <code>{@link org.quartz.Trigger}</code> s
363      * that have the given group name.
364      * </p>
365      * 
366      * <p>
367      * If there are no triggers in the given group name, the result should be a
368      * zero-length array (not <code>null</code>).
369      * </p>
370      */
371     String  [] getTriggerNames(SchedulingContext ctxt, String   groupName)
372         throws JobPersistenceException;
373 
374     /**
375      * <p>
376      * Get the names of all of the <code>{@link org.quartz.Job}</code>
377      * groups.
378      * </p>
379      * 
380      * <p>
381      * If there are no known group names, the result should be a zero-length
382      * array (not <code>null</code>).
383      * </p>
384      */
385     String  [] getJobGroupNames(SchedulingContext ctxt)
386         throws JobPersistenceException;
387 
388     /**
389      * <p>
390      * Get the names of all of the <code>{@link org.quartz.Trigger}</code>
391      * groups.
392      * </p>
393      * 
394      * <p>
395      * If there are no known group names, the result should be a zero-length
396      * array (not <code>null</code>).
397      * </p>
398      */
399     String  [] getTriggerGroupNames(SchedulingContext ctxt)
400         throws JobPersistenceException;
401 
402     /**
403      * <p>
404      * Get the names of all of the <code>{@link org.quartz.Calendar}</code> s
405      * in the <code>JobStore</code>.
406      * </p>
407      * 
408      * <p>
409      * If there are no Calendars in the given group name, the result should be
410      * a zero-length array (not <code>null</code>).
411      * </p>
412      */
413     String  [] getCalendarNames(SchedulingContext ctxt)
414         throws JobPersistenceException;
415 
416     /**
417      * <p>
418      * Get all of the Triggers that are associated to the given Job.
419      * </p>
420      * 
421      * <p>
422      * If there are no matches, a zero-length array should be returned.
423      * </p>
424      */
425     Trigger[] getTriggersForJob(SchedulingContext ctxt, String   jobName,
426             String   groupName) throws JobPersistenceException;
427 
428     /**
429      * <p>
430      * Get the current state of the identified <code>{@link Trigger}</code>.
431      * </p>
432      * 
433      * @see Trigger#STATE_NORMAL
434      * @see Trigger#STATE_PAUSED
435      * @see Trigger#STATE_COMPLETE
436      * @see Trigger#STATE_ERROR
437      * @see Trigger#STATE_NONE
438      */
439     int getTriggerState(SchedulingContext ctxt, String   triggerName,
440             String   triggerGroup) throws JobPersistenceException;
441 
442     /////////////////////////////////////////////////////////////////////////////
443     //
444     // Trigger State manipulation methods
445     //
446     /////////////////////////////////////////////////////////////////////////////
447 
448     /**
449      * <p>
450      * Pause the <code>{@link org.quartz.Trigger}</code> with the given name.
451      * </p>
452      * 
453      * @see #resumeTrigger(SchedulingContext, String, String)
454      */
455     void pauseTrigger(SchedulingContext ctxt, String   triggerName,
456             String   groupName) throws JobPersistenceException;
457 
458     /**
459      * <p>
460      * Pause all of the <code>{@link org.quartz.Trigger}s</code> in the
461      * given group.
462      * </p>
463      * 
464      * 
465      * <p>
466      * The JobStore should "remember" that the group is paused, and impose the
467      * pause on any new triggers that are added to the group while the group is
468      * paused.
469      * </p>
470      * 
471      * @see #resumeTriggerGroup(SchedulingContext, String)
472      */
473     void pauseTriggerGroup(SchedulingContext ctxt, String   groupName)
474         throws JobPersistenceException;
475 
476     /**
477      * <p>
478      * Pause the <code>{@link org.quartz.Job}</code> with the given name - by
479      * pausing all of its current <code>Trigger</code>s.
480      * </p>
481      * 
482      * @see #resumeJob(SchedulingContext, String, String)
483      */
484     void pauseJob(SchedulingContext ctxt, String   jobName,
485             String   groupName) throws JobPersistenceException;
486 
487     /**
488      * <p>
489      * Pause all of the <code>{@link org.quartz.Job}s</code> in the given
490      * group - by pausing all of their <code>Trigger</code>s.
491      * </p>
492      * 
493      * <p>
494      * The JobStore should "remember" that the group is paused, and impose the
495      * pause on any new jobs that are added to the group while the group is
496      * paused.
497      * </p>
498      * 
499      * @see #resumeJobGroup(SchedulingContext, String)
500      */
501     void pauseJobGroup(SchedulingContext ctxt, String   groupName)
502         throws JobPersistenceException;
503 
504     /**
505      * <p>
506      * Resume (un-pause) the <code>{@link org.quartz.Trigger}</code> with the
507      * given name.
508      * </p>
509      * 
510      * <p>
511      * If the <code>Trigger</code> missed one or more fire-times, then the
512      * <code>Trigger</code>'s misfire instruction will be applied.
513      * </p>
514      * 
515      * @see #pauseTrigger(SchedulingContext, String, String)
516      */
517     void resumeTrigger(SchedulingContext ctxt, String   triggerName,
518             String   groupName) throws JobPersistenceException;
519 
520     /**
521      * <p>
522      * Resume (un-pause) all of the <code>{@link org.quartz.Trigger}s</code>
523      * in the given group.
524      * </p>
525      * 
526      * <p>
527      * If any <code>Trigger</code> missed one or more fire-times, then the
528      * <code>Trigger</code>'s misfire instruction will be applied.
529      * </p>
530      * 
531      * @see #pauseTriggerGroup(SchedulingContext, String)
532      */
533     void resumeTriggerGroup(SchedulingContext ctxt, String   groupName)
534         throws JobPersistenceException;
535 
536     Set   getPausedTriggerGroups(SchedulingContext ctxt)
537         throws JobPersistenceException;
538 
539 
540     /**
541      * <p>
542      * Resume (un-pause) the <code>{@link org.quartz.Job}</code> with the
543      * given name.
544      * </p>
545      * 
546      * <p>
547      * If any of the <code>Job</code>'s<code>Trigger</code> s missed one
548      * or more fire-times, then the <code>Trigger</code>'s misfire
549      * instruction will be applied.
550      * </p>
551      * 
552      * @see #pauseJob(SchedulingContext, String, String)
553      */
554     void resumeJob(SchedulingContext ctxt, String   jobName,
555             String   groupName) throws JobPersistenceException;
556 
557     /**
558      * <p>
559      * Resume (un-pause) all of the <code>{@link org.quartz.Job}s</code> in
560      * the given group.
561      * </p>
562      * 
563      * <p>
564      * If any of the <code>Job</code> s had <code>Trigger</code> s that
565      * missed one or more fire-times, then the <code>Trigger</code>'s
566      * misfire instruction will be applied.
567      * </p>
568      * 
569      * @see #pauseJobGroup(SchedulingContext, String)
570      */
571     void resumeJobGroup(SchedulingContext ctxt, String   groupName)
572         throws JobPersistenceException;
573 
574     /**
575      * <p>
576      * Pause all triggers - equivalent of calling <code>pauseTriggerGroup(group)</code>
577      * on every group.
578      * </p>
579      * 
580      * <p>
581      * When <code>resumeAll()</code> is called (to un-pause), trigger misfire
582      * instructions WILL be applied.
583      * </p>
584      * 
585      * @see #resumeAll(SchedulingContext)
586      * @see #pauseTriggerGroup(SchedulingContext, String)
587      */
588     void pauseAll(SchedulingContext ctxt) throws JobPersistenceException;
589 
590     /**
591      * <p>
592      * Resume (un-pause) all triggers - equivalent of calling <code>resumeTriggerGroup(group)</code>
593      * on every group.
594      * </p>
595      * 
596      * <p>
597      * If any <code>Trigger</code> missed one or more fire-times, then the
598      * <code>Trigger</code>'s misfire instruction will be applied.
599      * </p>
600      * 
601      * @see #pauseAll(SchedulingContext)
602      */
603     void resumeAll(SchedulingContext ctxt)
604         throws JobPersistenceException;
605 
606     /////////////////////////////////////////////////////////////////////////////
607     //
608     // Trigger-Firing methods
609     //
610     /////////////////////////////////////////////////////////////////////////////
611 
612     /**
613      * <p>
614      * Get a handle to the next trigger to be fired, and mark it as 'reserved'
615      * by the calling scheduler.
616      * </p>
617      *
618      * @param noLaterThan If > 0, the JobStore should only return a Trigger 
619      * that will fire no later than the time represented in this value as 
620      * milliseconds.
621      * @see #releaseAcquiredTrigger(SchedulingContext, Trigger)
622      */
623     Trigger acquireNextTrigger(SchedulingContext ctxt, long noLaterThan)
624         throws JobPersistenceException;
625 
626     /**
627      * <p>
628      * Inform the <code>JobStore</code> that the scheduler no longer plans to
629      * fire the given <code>Trigger</code>, that it had previously acquired
630      * (reserved).
631      * </p>
632      */
633     void releaseAcquiredTrigger(SchedulingContext ctxt, Trigger trigger)
634         throws JobPersistenceException;
635 
636     /**
637      * <p>
638      * Inform the <code>JobStore</code> that the scheduler is now firing the
639      * given <code>Trigger</code> (executing its associated <code>Job</code>),
640      * that it had previously acquired (reserved).
641      * </p>
642      * 
643      * @return null if the trigger or it's job or calendar no longer exist, or
644      *         if the trigger was not successfully put into the 'executing'
645      *         state.
646      */
647     TriggerFiredBundle triggerFired(SchedulingContext ctxt,
648             Trigger trigger) throws JobPersistenceException;
649 
650     /**
651      * <p>
652      * Inform the <code>JobStore</code> that the scheduler has completed the
653      * firing of the given <code>Trigger</code> (and the execution of its
654      * associated <code>Job</code> completed, threw an exception, or was vetoed),
655      * and that the <code>{@link org.quartz.JobDataMap}</code>
656      * in the given <code>JobDetail</code> should be updated if the <code>Job</code>
657      * is stateful.
658      * </p>
659      */
660     void triggeredJobComplete(SchedulingContext ctxt, Trigger trigger,
661             JobDetail jobDetail, int triggerInstCode)
662         throws JobPersistenceException;
663 
664 }
665
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags