/* * Copyright 2001-2009 James House * * 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. * */ /* * Previously Copyright (c) 2001-2004 James House */ package org.quartz.spi; import java.util.Set; import org.quartz.Calendar; import org.quartz.JobDetail; import org.quartz.JobPersistenceException; import org.quartz.ObjectAlreadyExistsException; import org.quartz.SchedulerConfigException; import org.quartz.SchedulerException; import org.quartz.Trigger; import org.quartz.core.SchedulingContext; /** *

* The interface to be implemented by classes that want to provide a {@link org.quartz.Job} * and {@link org.quartz.Trigger} storage mechanism for the * {@link org.quartz.core.QuartzScheduler}'s use. *

* *

* Storage of Job s and Trigger s should be keyed * on the combination of their name and group for uniqueness. *

* * @see org.quartz.core.QuartzScheduler * @see org.quartz.Trigger * @see org.quartz.Job * @see org.quartz.JobDetail * @see org.quartz.JobDataMap * @see org.quartz.Calendar * * @author James House * @author Eric Mueller */ public interface JobStore { /* * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * * Interface. * * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ /** *

* Called by the QuartzScheduler before the JobStore is * used, in order to give the it a chance to initialize. *

*/ void initialize(ClassLoadHelper loadHelper, SchedulerSignaler signaler) throws SchedulerConfigException; /** *

* Called by the QuartzScheduler to inform the JobStore that * the scheduler has started. *

*/ void schedulerStarted() throws SchedulerException ; /** *

* Called by the QuartzScheduler to inform the JobStore that * it should free up all of it's resources because the scheduler is * shutting down. *

*/ void shutdown(); boolean supportsPersistence(); ///////////////////////////////////////////////////////////////////////////// // // Job & Trigger Storage methods // ///////////////////////////////////////////////////////////////////////////// /** *

* Store the given {@link org.quartz.JobDetail} and {@link org.quartz.Trigger}. *

* * @param newJob * The JobDetail to be stored. * @param newTrigger * The Trigger to be stored. * @throws ObjectAlreadyExistsException * if a Job with the same name/group already * exists. */ void storeJobAndTrigger(SchedulingContext ctxt, JobDetail newJob, Trigger newTrigger) throws ObjectAlreadyExistsException, JobPersistenceException; /** *

* Store the given {@link org.quartz.JobDetail}. *

* * @param newJob * The JobDetail to be stored. * @param replaceExisting * If true, any Job existing in the * JobStore with the same name & group should be * over-written. * @throws ObjectAlreadyExistsException * if a Job with the same name/group already * exists, and replaceExisting is set to false. */ void storeJob(SchedulingContext ctxt, JobDetail newJob, boolean replaceExisting) throws ObjectAlreadyExistsException, JobPersistenceException; /** *

* Remove (delete) the {@link org.quartz.Job} with the given * name, and any {@link org.quartz.Trigger} s that reference * it. *

* *

* If removal of the Job results in an empty group, the * group should be removed from the JobStore's list of * known group names. *

* * @param jobName * The name of the Job to be removed. * @param groupName * The group name of the Job to be removed. * @return true if a Job with the given name & * group was found and removed from the store. */ boolean removeJob(SchedulingContext ctxt, String jobName, String groupName) throws JobPersistenceException; /** *

* Retrieve the {@link org.quartz.JobDetail} for the given * {@link org.quartz.Job}. *

* * @param jobName * The name of the Job to be retrieved. * @param groupName * The group name of the Job to be retrieved. * @return The desired Job, or null if there is no match. */ JobDetail retrieveJob(SchedulingContext ctxt, String jobName, String groupName) throws JobPersistenceException; /** *

* Store the given {@link org.quartz.Trigger}. *

* * @param newTrigger * The Trigger to be stored. * @param replaceExisting * If true, any Trigger existing in * the JobStore with the same name & group should * be over-written. * @throws ObjectAlreadyExistsException * if a Trigger with the same name/group already * exists, and replaceExisting is set to false. * * @see #pauseTriggerGroup(SchedulingContext, String) */ void storeTrigger(SchedulingContext ctxt, Trigger newTrigger, boolean replaceExisting) throws ObjectAlreadyExistsException, JobPersistenceException; /** *

* Remove (delete) the {@link org.quartz.Trigger} with the * given name. *

* *

* If removal of the Trigger results in an empty group, the * group should be removed from the JobStore's list of * known group names. *

* *

* If removal of the Trigger results in an 'orphaned' Job * that is not 'durable', then the Job should be deleted * also. *

* * @param triggerName * The name of the Trigger to be removed. * @param groupName * The group name of the Trigger to be removed. * @return true if a Trigger with the given * name & group was found and removed from the store. */ boolean removeTrigger(SchedulingContext ctxt, String triggerName, String groupName) throws JobPersistenceException; /** *

* Remove (delete) the {@link org.quartz.Trigger} with the * given name, and store the new given one - which must be associated * with the same job. *

* * @param triggerName * The name of the Trigger to be removed. * @param groupName * The group name of the Trigger to be removed. * @param newTrigger * The new Trigger to be stored. * @return true if a Trigger with the given * name & group was found and removed from the store. */ boolean replaceTrigger(SchedulingContext ctxt, String triggerName, String groupName, Trigger newTrigger) throws JobPersistenceException; /** *

* Retrieve the given {@link org.quartz.Trigger}. *

* * @param triggerName * The name of the Trigger to be retrieved. * @param groupName * The group name of the Trigger to be retrieved. * @return The desired Trigger, or null if there is no * match. */ Trigger retrieveTrigger(SchedulingContext ctxt, String triggerName, String groupName) throws JobPersistenceException; /** *

* Store the given {@link org.quartz.Calendar}. *

* * @param calendar * The Calendar to be stored. * @param replaceExisting * If true, any Calendar existing * in the JobStore with the same name & group * should be over-written. * @param updateTriggers * If true, any Triggers existing * in the JobStore that reference an existing * Calendar with the same name with have their next fire time * re-computed with the new Calendar. * @throws ObjectAlreadyExistsException * if a Calendar with the same name already * exists, and replaceExisting is set to false. */ void storeCalendar(SchedulingContext ctxt, String name, Calendar calendar, boolean replaceExisting, boolean updateTriggers) throws ObjectAlreadyExistsException, JobPersistenceException; /** *

* Remove (delete) the {@link org.quartz.Calendar} with the * given name. *

* *

* If removal of the Calendar would result in * s pointing to non-existent calendars, then a * JobPersistenceException will be thrown.

* * * @param calName The name of the Calendar to be removed. * @return true if a Calendar with the given name * was found and removed from the store. */ boolean removeCalendar(SchedulingContext ctxt, String calName) throws JobPersistenceException; /** *

* Retrieve the given {@link org.quartz.Trigger}. *

* * @param calName * The name of the Calendar to be retrieved. * @return The desired Calendar, or null if there is no * match. */ Calendar retrieveCalendar(SchedulingContext ctxt, String calName) throws JobPersistenceException; ///////////////////////////////////////////////////////////////////////////// // // Informational methods // ///////////////////////////////////////////////////////////////////////////// /** *

* Get the number of {@link org.quartz.Job} s that are * stored in the JobsStore. *

*/ int getNumberOfJobs(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get the number of {@link org.quartz.Trigger} s that are * stored in the JobsStore. *

*/ int getNumberOfTriggers(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get the number of {@link org.quartz.Calendar} s that are * stored in the JobsStore. *

*/ int getNumberOfCalendars(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get the names of all of the {@link org.quartz.Job} s that * have the given group name. *

* *

* If there are no jobs in the given group name, the result should be a * zero-length array (not null). *

*/ String[] getJobNames(SchedulingContext ctxt, String groupName) throws JobPersistenceException; /** *

* Get the names of all of the {@link org.quartz.Trigger} s * that have the given group name. *

* *

* If there are no triggers in the given group name, the result should be a * zero-length array (not null). *

*/ String[] getTriggerNames(SchedulingContext ctxt, String groupName) throws JobPersistenceException; /** *

* Get the names of all of the {@link org.quartz.Job} * groups. *

* *

* If there are no known group names, the result should be a zero-length * array (not null). *

*/ String[] getJobGroupNames(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get the names of all of the {@link org.quartz.Trigger} * groups. *

* *

* If there are no known group names, the result should be a zero-length * array (not null). *

*/ String[] getTriggerGroupNames(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get the names of all of the {@link org.quartz.Calendar} s * in the JobStore. *

* *

* If there are no Calendars in the given group name, the result should be * a zero-length array (not null). *

*/ String[] getCalendarNames(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Get all of the Triggers that are associated to the given Job. *

* *

* If there are no matches, a zero-length array should be returned. *

*/ Trigger[] getTriggersForJob(SchedulingContext ctxt, String jobName, String groupName) throws JobPersistenceException; /** *

* Get the current state of the identified {@link Trigger}. *

* * @see Trigger#STATE_NORMAL * @see Trigger#STATE_PAUSED * @see Trigger#STATE_COMPLETE * @see Trigger#STATE_ERROR * @see Trigger#STATE_NONE */ int getTriggerState(SchedulingContext ctxt, String triggerName, String triggerGroup) throws JobPersistenceException; ///////////////////////////////////////////////////////////////////////////// // // Trigger State manipulation methods // ///////////////////////////////////////////////////////////////////////////// /** *

* Pause the {@link org.quartz.Trigger} with the given name. *

* * @see #resumeTrigger(SchedulingContext, String, String) */ void pauseTrigger(SchedulingContext ctxt, String triggerName, String groupName) throws JobPersistenceException; /** *

* Pause all of the {@link org.quartz.Trigger}s in the * given group. *

* * *

* The JobStore should "remember" that the group is paused, and impose the * pause on any new triggers that are added to the group while the group is * paused. *

* * @see #resumeTriggerGroup(SchedulingContext, String) */ void pauseTriggerGroup(SchedulingContext ctxt, String groupName) throws JobPersistenceException; /** *

* Pause the {@link org.quartz.Job} with the given name - by * pausing all of its current Triggers. *

* * @see #resumeJob(SchedulingContext, String, String) */ void pauseJob(SchedulingContext ctxt, String jobName, String groupName) throws JobPersistenceException; /** *

* Pause all of the {@link org.quartz.Job}s in the given * group - by pausing all of their Triggers. *

* *

* The JobStore should "remember" that the group is paused, and impose the * pause on any new jobs that are added to the group while the group is * paused. *

* * @see #resumeJobGroup(SchedulingContext, String) */ void pauseJobGroup(SchedulingContext ctxt, String groupName) throws JobPersistenceException; /** *

* Resume (un-pause) the {@link org.quartz.Trigger} with the * given name. *

* *

* If the Trigger missed one or more fire-times, then the * Trigger's misfire instruction will be applied. *

* * @see #pauseTrigger(SchedulingContext, String, String) */ void resumeTrigger(SchedulingContext ctxt, String triggerName, String groupName) throws JobPersistenceException; /** *

* Resume (un-pause) all of the {@link org.quartz.Trigger}s * in the given group. *

* *

* If any Trigger missed one or more fire-times, then the * Trigger's misfire instruction will be applied. *

* * @see #pauseTriggerGroup(SchedulingContext, String) */ void resumeTriggerGroup(SchedulingContext ctxt, String groupName) throws JobPersistenceException; Set getPausedTriggerGroups(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Resume (un-pause) the {@link org.quartz.Job} with the * given name. *

* *

* If any of the Job'sTrigger s missed one * or more fire-times, then the Trigger's misfire * instruction will be applied. *

* * @see #pauseJob(SchedulingContext, String, String) */ void resumeJob(SchedulingContext ctxt, String jobName, String groupName) throws JobPersistenceException; /** *

* Resume (un-pause) all of the {@link org.quartz.Job}s in * the given group. *

* *

* If any of the Job s had Trigger s that * missed one or more fire-times, then the Trigger's * misfire instruction will be applied. *

* * @see #pauseJobGroup(SchedulingContext, String) */ void resumeJobGroup(SchedulingContext ctxt, String groupName) throws JobPersistenceException; /** *

* Pause all triggers - equivalent of calling pauseTriggerGroup(group) * on every group. *

* *

* When resumeAll() is called (to un-pause), trigger misfire * instructions WILL be applied. *

* * @see #resumeAll(SchedulingContext) * @see #pauseTriggerGroup(SchedulingContext, String) */ void pauseAll(SchedulingContext ctxt) throws JobPersistenceException; /** *

* Resume (un-pause) all triggers - equivalent of calling resumeTriggerGroup(group) * on every group. *

* *

* If any Trigger missed one or more fire-times, then the * Trigger's misfire instruction will be applied. *

* * @see #pauseAll(SchedulingContext) */ void resumeAll(SchedulingContext ctxt) throws JobPersistenceException; ///////////////////////////////////////////////////////////////////////////// // // Trigger-Firing methods // ///////////////////////////////////////////////////////////////////////////// /** *

* Get a handle to the next trigger to be fired, and mark it as 'reserved' * by the calling scheduler. *

* * @param noLaterThan If > 0, the JobStore should only return a Trigger * that will fire no later than the time represented in this value as * milliseconds. * @see #releaseAcquiredTrigger(SchedulingContext, Trigger) */ Trigger acquireNextTrigger(SchedulingContext ctxt, long noLaterThan) throws JobPersistenceException; /** *

* Inform the JobStore that the scheduler no longer plans to * fire the given Trigger, that it had previously acquired * (reserved). *

*/ void releaseAcquiredTrigger(SchedulingContext ctxt, Trigger trigger) throws JobPersistenceException; /** *

* Inform the JobStore that the scheduler is now firing the * given Trigger (executing its associated Job), * that it had previously acquired (reserved). *

* * @return null if the trigger or it's job or calendar no longer exist, or * if the trigger was not successfully put into the 'executing' * state. */ TriggerFiredBundle triggerFired(SchedulingContext ctxt, Trigger trigger) throws JobPersistenceException; /** *

* Inform the JobStore that the scheduler has completed the * firing of the given Trigger (and the execution of its * associated Job completed, threw an exception, or was vetoed), * and that the {@link org.quartz.JobDataMap} * in the given JobDetail should be updated if the Job * is stateful. *

*/ void triggeredJobComplete(SchedulingContext ctxt, Trigger trigger, JobDetail jobDetail, int triggerInstCode) throws JobPersistenceException; }